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.
Calling Sequence
#define INCL_SPL /* Or use INCL_PM, */ #include <os2.h> PSZ pszComputerName; /* Name of computer where print device is to be queried. */ PSZ pszPrintDeviceName; /* Name of Print Device. */ ULONG ulLevel; /* Level of detail required. */ PVOID pBuf; /* Buffer. */ ULONG cbBuf; /* Size, in bytes, of Buffer. */ PULONG pcbNeeded; /* Size in bytes of available information. */ SPLERR rc; /* Return code. */ rc = SplQueryDevice(pszComputerName, pszPrintDeviceName, ulLevel, pBuf, cbBuf, pcbNeeded);
Sample
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.