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.

Related Functions

• SplCreateDevice
• SplDeleteDevice