SplQueryDevice: Difference between revisions
Appearance
Created page with "This function retrieves information about a print device. ==Syntax== SplQueryDevice(pszComputerName, pszPrintDeviceName, ulLevel, pBuf, cbBuf, pcbNeeded); ==Parameters== ;p..." |
|||
Line 151: | Line 151: | ||
If ulLevel is 0, the port name in pBuf is truncated to 8 characters. | 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 | 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. | 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. | If no job is printing on the print device, bits 2-11 of fsStatus in the [[PRDINFO3]] data structure are meaningless. | ||
==Related Functions== | ==Related Functions== |
Revision as of 04:29, 29 February 2020
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.