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



 * 1) define INCL_SPL /* Or use INCL_PM, */
 * 2) include 

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. 
 * 1) define INCL_BASE
 * 2) define INCL_DOSMEMMGR
 * 3) define INCL_SPL
 * 4) define INCL_SPLDOSPRINT
 * 5) define INCL_SPLERRORS


 * 1) include 
 * 2) include 

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.

Related Functions

 * SplCreateDevice
 * SplDeleteDevice
 * SplEnumDevice