SplQueryDevice
This function retrieves information about a print device.
Syntax
SplQueryDevice(pszComputerName, pszPrintDeviceName, ulLevel, pBuf, cbBuf, pcbNeeded)
Parameters
- pszComputerName (PSZ) - input
- Name of computer where print device is to be queried.
- A NULL string specifies the local workstation.
- pszPrintDeviceName (PSZ) - input
- Name of Print Device.
- This can specify a print device name or a port name. If ulLevel is 0, it must be a port name. If ulLevel is 2 or 3, it must be a print device name.
- ulLevel (ULONG) - input
- Level of detail required.
- This must be 0, 2 or 3.
- pBuf (PVOID) - in/out
- Buffer.
- The returned contents of the buffer depend on the value specified in ulLevel as follows:
- ulLevel Buffer Contents
- 0 A port name consisting of 9 characters, including a null terminator.
- 2 A print device name of type PSZ.
- 3 A PRDINFO3 structure.
- cbBuf (ULONG) - input
- Size, in bytes, of Buffer.
- It must be greater than 0.
- pcbNeeded (PULONG) - output
- Size in bytes of available information.
Return Code
- rc (SPLERR) - returns
- Return code.
- NO_ERROR (0) No errors occurred.
- ERROR_NOT_SUPPORTED (50) This request is not supported by the network.
- ERROR_BAD_NETPATH (53) The network path cannot be located.
- ERROR_INVALID_PARAMETER (87) An invalid parameter is specified.
- ERROR_INVALID_LEVEL (124) The level parameter is invalid.
- ERROR_MORE_DATA (234) Additional data is available.
- NERR_NetNotStarted (2102) The network program is not started.
- NERR_BufTooSmall (2123) The API return buffer is too small.
- NERR_DestNotFound (2152) The print device cannot be found.
- NERR_InvalidComputer (2351) The computer name is invalid.
Example
This sample code returns information for the device name that is entered at the command line. The local workstation is selected. The query is done for level 3 information.
#define INCL_BASE
#define INCL_DOSMEMMGR
#define INCL_SPL
#define INCL_SPLDOSPRINT
#define INCL_SPLERRORS
#include <os2.h>
#include <stdio.h>
INT main (argc, argv)
INT argc;
CHAR *argv[];
{
SPLERR splerr;
ULONG cbBuf;
ULONG cbNeeded;
ULONG ulLevel;
PSZ pszComputerName;
PSZ pszPrintDeviceName;
PVOID pBuf;
PPRDINFO3 pprd3;
if (argc != 2)
{
printf("Syntax: sdqry DeviceName\n");
DosExit(EXIT_PROCESS, 0);
}
pszComputerName = (PSZ)NULL;
pszPrintDeviceName = argv[1];
ulLevel = 3;
splerr = SplQueryDevice(pszComputerName, pszPrintDeviceName,
ulLevel, (PVOID)NULL, 0L, &cbNeeded );
if (splerr != NERR_BufTooSmall)
{
printf("SplQueryDevice Err=%ld, cbNeeded=%ld\n",splerr, cbNeeded);
DosExit( EXIT_PROCESS , 0);
}
if (!DosAllocMem( &pBuf, cbNeeded,
PAG_READ|PAG_WRITE|PAG_COMMIT) ){
cbBuf= cbNeeded ;
splerr = SplQueryDevice(pszComputerName, pszPrintDeviceName,
ulLevel, pBuf, cbBuf, &cbNeeded);
printf("SplQueryDevice Error=%ld, Bytes Needed=%ld\n", splerr,
cbNeeded);
pprd3=(PPRDINFO3)pBuf;
printf("Print Device info: name - %s\n", pprd3->pszPrinterName);
printf("User Name = %s\n", pprd3->pszUserName);
printf("Logical Address= %s\n", pprd3->pszLogAddr);
printf("Job ID = %d\n", pprd3->uJobId);
printf("Status = %d\n", pprd3->fsStatus);
printf("Status Comment = %s\n", pprd3->pszStatus);
printf("Comment = %s\n", pprd3->pszComment);
printf("Drivers = %s\n", pprd3->pszDrivers);
printf("Time = %d\n", pprd3->time);
printf("Time Out = %d\n", pprd3->usTimeOut);
DosFreeMem(pBuf);
}
DosExit( EXIT_PROCESS, 0 );
return (splerr);
}
Remarks
If ulLevel is 0, the port name in pBuf is truncated to 8 characters.
If ulLevel is 3, and pBuf cannot hold the entire PRDINFO3 structure, SplQueryDevice returns NERR_BufTooSmall (2123).
To obtain the size of buffer required, call SplQueryDevice with the required value of ulLevel and a NULL buffer. The number of bytes required is returned in pcbNeeded.
If no job is printing on the print device, bits 2-11 of fsStatus in the PRDINFO3 data structure are meaningless.