SplEnumDevice
This function lists print device on a server, optionally supplying status information.
Syntax
SplEnumDevice(pszComputerName, ulLevel, pBuf, cbBuf, pcReturned, pcTotal, pcbNeeded, pReserved);
Parameters
- pszComputerName (PSZ) - input
- Name of computer where print devices are to. be listed.
- A NULL string specifies the local workstation.
- ulLevel (ULONG) - input
- Level of detail required.
- This must be 0, 2 or 3.
- pBuf (PVOID) - output
- Buffer.
- The returned contents of the buffer depend on the value indicated in ulLevel as follows:
- ulLevel Buffer Contents
- 0 An array of port names. Each name consists of 9 characters, including a null terminator.
- 2 An array of print device names of type PSZ.
- 3 An array of PRDINFO3 structures.
- If no job is printing on the print device, bits 2-11 of fsStatus in the PRDINFO3 data structure are meaningless.
- cbBuf (ULONG) - input
- Size, in bytes, of Buffer.
- It must be greater than 0.
- pcReturned (PULONG) - output
- Number of entries returned.
- pcTotal (PULONG) - output
- Number of entries available.
- pcbNeeded (PULONG) - output
- Size in bytes of available information.
- A value of 0 specifies that the size is not known.
- pReserved (PVOID) - output
- Reserved value, must be NULL.
Returns
- 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_InvalidComputer (2351)
- The computer name is invalid.
Sample
This sample code enumerates all the devices on the local workstation. It then prints out the information.
#define INCL_BASE
#define INCL_DOSMEMMGR
#define INCL_SPL
#define INCL_SPLDOSPRINT
#define INCL_SPLERRORS
#include <os2.h>
#include <stdio.h>
INT main ()
{
ULONG cbBuf ;
ULONG cTotal;
ULONG cReturned ;
ULONG cbNeeded ;
ULONG ulLevel = 3L;
ULONG i ;
SPLERR splerr ;
PSZ pszComputerName ;
PBYTE pBuf ;
PPRDINFO3 pprd3 ;
pszComputerName = (PSZ)NULL ;
/* Make the call with cBuf = 0 so that you will get the size of the */
/* buffer needed returned in cbNeeded. */
splerr = SplEnumDevice(pszComputerName, ulLevel, pBuf, 0L, /* cbBuf */
&cReturned, &cTotal, &cbNeeded,
NULL) ;
/* Only continue if the error codes ERROR_MORE_DATA or */
/* NERR_BufTooSmall are returned. */
if (splerr == ERROR_MORE_DATA || splerr == NERR_BufTooSmall)
{
/* Allocate memory for the buffer that will hold the returning info. */
if (!DosAllocMem( &pBuf, cbNeeded,
PAG_READ|PAG_WRITE|PAG_COMMIT) )
{
cbBuf = cbNeeded ;
/* Make call again with the proper buffer size. */
splerr = SplEnumDevice(pszComputerName, ulLevel, pBuf, cbBuf,
&cReturned, &cTotal,
&cbNeeded, NULL) ;
/* If no errors, print out the buffer information. */
if (splerr == NO_ERROR)
{
for (i=0;i < cReturned ; i++)
{
/* Each time through the loop increase the pointer. */
pprd3 = (PPRDINFO3)pBuf+i ;
printf("Device info:pszPrinterName - %s\n",
pprd3->pszPrinterName) ;
printf(" pszUserName - %s\n", pprd3->pszUserName);
printf(" pszLogAddr - %s\n", pprd3->pszLogAddr);
printf(" uJobId - %d fsStatus - %X\n",
pprd3->uJobId , pprd3->fsStatus);
printf(" pszStatus - %s\n", pprd3->pszStatus);
printf(" pszComment - %s\n", pprd3->pszComment);
printf(" pszDrivers - %s\n", pprd3->pszDrivers);
printf(" time - %d usTimeOut - %X\n",
pprd3->time , pprd3->usTimeOut);
}
}
DosFreeMem(pBuf) ;
}
} /* end if */
else
{
printf("SplEnumDevice splerr=%ld, cTotal=%ld, cReturned=%ld, cbNeeded=%ld\n",
splerr, cTotal, cReturned, cbNeeded) ;
}
DosExit( EXIT_PROCESS , 0 ) ;
return(splerr);
} /* end main */
Call Sequence
#define INCL_SPL /* Or use INCL_PM, */
#include <os2.h>
PSZ pszComputerName; /* Name of computer where print devices are to. be listed. */
ULONG ulLevel; /* Level of detail required. */
PVOID pBuf; /* Buffer. */
ULONG cbBuf; /* Size, in bytes, of Buffer. */
PULONG pcReturned; /* Number of entries returned. */
PULONG pcTotal; /* Number of entries available. */
PULONG pcbNeeded; /* Size in bytes of available information. */
PVOID pReserved; /* Reserved value, must be NULL. */
SPLERR rc; /* Return code. */
rc = SplEnumDevice(pszComputerName, ulLevel,
pBuf, cbBuf, pcReturned, pcTotal, pcbNeeded,
pReserved);
Remarks
If ulLevel is set to 0, each port name in pBuf is truncated to 8 characters.