SplEnumPort
This function lists printer ports on the local workstation or on a remote server.
Syntax
SplEnumPort(pszComputerName, ulLevel, pBuf, cbBuf, pcReturned, pcTotal, pcbNeeded, pReserved)
Parameters
- pszComputerName (PSZ) - input
- Name of computer where queues are to be listed.
- A NULL string specifies the local workstation.
- ulLevel (ULONG) - input
- Level of detail.
- The level of detail required. This must be 0 or 1.
- pBuf (PVOID) - output
- Buffer.
- The returned content in the buffer depends on the value specified in ulLevel as follows:
- ulLevel Buffer Contents
- 0 An array of PRPORTINFO structures
- 1 An array of PRPORTINFO1 structures
- cbBuf (ULONG) - input
- Size, in bytes, of Buffer.
- pcReturned (PULONG) - output
- Number of entries returned.
- pcTotal (PULONG) - output
- Total 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.
- This must be NULL.
Returns
- rc (SPLERR) - returns
- Return code.
- NO_ERROR (0) : No errors occurred.
- ERROR_ACCESS_DENIED (5) : Access is denied.
- 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_InvalidComputer (2351) : The computer name is invalid.
Sample
This sample code will print out all the ports an associated information. This is done at level 1, and for the local workstation.
#define INCL_DOSMEMMGR
#define INCL_SPL
#define INCL_SPLDOSPRINT
#define INCL_SPLERRORS
#include <os2.h>
#include <stdio.h>
INT main ()
{
SPLERR splerr ;
ULONG cbBuf ;
ULONG cTotal;
ULONG cReturned ;
ULONG cbNeeded ;
ULONG ulLevel = 1;
ULONG i ;
PSZ pszComputerName = NULL;
PVOID pbuf ;
PPRPORTINFO1 pPort1 ;
splerr = SplEnumPort(pszComputerName, ulLevel, pbuf, 0L, /* cbBuf */
&cReturned, &cTotal,
&cbNeeded, NULL) ;
if (splerr == ERROR_MORE_DATA || NERR_BufTooSmall )
{
if (!DosAllocMem( &pbuf, cbNeeded,
PAG_READ|PAG_WRITE|PAG_COMMIT) )
{
cbBuf = cbNeeded ;
splerr = SplEnumPort(pszComputerName, ulLevel, pbuf, cbBuf,
&cReturned, &cTotal,
&cbNeeded, NULL) ;
if (splerr == 0L)
{
pPort1 = (PPRPORTINFO1)pbuf ;
printf("Port names: ");
for (i=0; i < cReturned; i++)
{
printf("Port - %s, Driver - %s Path - %s\n ",
pPort1->pszPortName, pPort1->pszPortDriverName,
pPort1->pszPortDriverPathName ) ;
pPort1++ ;
}
printf("\n");
}
DosFreeMem(pbuf) ;
}
}
else
{
printf("SplEnumPort splerr=%ld, \n",splerr) ;
}
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 queues are to be listed. */
ULONG ulLevel; /* Level of detail. */
PVOID pBuf; /* Buffer. */
ULONG cbBuf; /* Size, in bytes, of Buffer. */
PULONG pcReturned; /* Number of entries returned. */
PULONG pcTotal; /* Total number of entries available. */
PULONG pcbNeeded; /* Size in bytes of available information. */
PVOID pReserved; /* Reserved. */
SPLERR rc; /* Return code. */
rc = SplEnumPort(pszComputerName, ulLevel,
pBuf, cbBuf, pcReturned, pcTotal, pcbNeeded,
pReserved);