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);

Related Functions

• SplCreateDevice
• SplSetDevice