SplEnumPrinter

This function lists print destinations in the system.

Syntax

SplEnumPrinter(PSZComputerName, ulLevel, flType, pBuf, cbBuf,
               pcReturned, pcTotal, pcbNeeded, pReserved)

Parameters

PSZComputerName (PSZ) - input

Name of computer where queues are to be listed.

This must be NULL.

ulLevel (ULONG) - input

Level of detail required.

This must be 0.

flType (ULONG) - input

Type of print destinations required.

SPL_PR_QUEUE: Return only queues

SPL_PR_DIRECT_DEVICE: Return only direct print devices

SPL_PR_QUEUED_DEVICE: Return only queued print devices

SPL_PR_LOCAL_ONLY: Return only local print destinations

pBuf (PVOID) - output

Buffer.

The returned contents in the buffer are as follows:

ulLevel Buffer Contents

0 An array of PRINTERINFO structures.

When the names of print destinations are returned, calls can be made to SplQueryQueue or SplQueryDevice to find out further information about the print destination.

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.

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_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.

Calling 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 required. */
ULONG     flType;           /*  Type of print destinations 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 = SplEnumPrinter(PSZComputerName, ulLevel,
       flType, pBuf, cbBuf, pcReturned, pcTotal,
       pcbNeeded, pReserved);

Sample

This example code will print out all queues and printers for the local computer. It will print out both printers that are attached to a queue, and those that are direct printers.

#define INCL_SPL
#define INCL_SPLDOSPRINT
#define INCL_SPLERRORS
#include <os2.h>
#include <stdio.h>      /* for printf function */

INT main ()
{
    PVOID pBuf;
    ULONG fsType;
    ULONG cbBuf;
    ULONG cRes;
    ULONG cTotal;
    ULONG cbNeeded;
    SPLERR splerr = 0;
    PPRINTERINFO pRes;

    /* Set fsType to use all the flags. We will print out local device/queues.*/
    fsType = SPL_PR_QUEUE | SPL_PR_DIRECT_DEVICE |
             SPL_PR_QUEUED_DEVICE | SPL_PR_LOCAL_ONLY;

    /* Make function call with cbBuf equal to zero to get a return in cbNeeded*/
    /* of the number of bytes needed for  buffer to hold all the information  */

    splerr = SplEnumPrinter ( NULL,0 ,fsType ,NULL ,NULL ,&cRes ,
                                 &cTotal,&cbNeeded ,NULL ) ;

    /* The error return code will be one of the two following codes if        */
    /* all the parameters were correct.  Otherwise it could be                */
    /* ERROR_INVALID_PARAMETER.                                         */

    if ( splerr == ERROR_MORE_DATA || splerr == NERR_BufTooSmall )
    {
       /* Allocate memory for the buffer using the count of bytes that were   */
       /* returned in cbNeeded.  For simplicity, no error checking is done.   */
       DosAllocMem( &pBuf, cbNeeded,
                    PAG_READ|PAG_WRITE|PAG_COMMIT);

       /* Set count of bytes in buffer to value used to allocate buffer.      */
       cbBuf = cbNeeded;

       /* Call function again with the correct buffer size.                   */
       splerr = SplEnumPrinter  ( NULL,0 ,fsType ,pBuf ,cbBuf ,&cRes ,
                                  &cTotal,&cbNeeded,NULL);

       /* If there are any returned structures in the buffer, then we will    */
       /* print out some of the information.                                  */
       if (cRes)
       {
          pRes = (PPRINTERINFO)pBuf ;
          while ( cRes-- )
          {
             /* Look at the flType element in the pRes structure to determine */
             /* what type of print destination the structure represents.      */
             switch (pRes[cRes].flType)
             {
                case  SPL_PR_QUEUE:
                   printf("Print destination %s is a queue.\n",
                   pRes[cRes].pszPrintDestinationName) ;
                   break;
                case SPL_PR_QUEUED_DEVICE:
                   printf("Print destination %s is a queued printer.\n",
                   pRes[cRes].pszPrintDestinationName) ;
                   break;
                case SPL_PR_DIRECT_DEVICE:
                   printf("Print destination %s is a direct printer.\n",
                   pRes[cRes].pszPrintDestinationName) ;
             }
             printf("Description -
                    %s\n\n",pRes[cRes].pszDescription) ;
          }
       }
       DosFreeMem(pBuf);
    }
    else
    {
       /* If we had any other return code other than ERROR_MORE_DATA or */
       /* NERR_BufTooSmall, we will print out the following information.*/
       printf("SplEnumPrinter error= %ld \n",splerr);
    }
    DosExit( EXIT_PROCESS , 0 ) ;
    return (splerr);
}