SplQueryDevice

This function retrieves information about a print device.

Syntax

SplQueryDevice(pszComputerName, pszPrintDeviceName, ulLevel, pBuf, cbBuf, pcbNeeded)

Parameters

pszComputerName (PSZ) - input

Name of computer where print device is to be queried.

A NULL string specifies the local workstation.

pszPrintDeviceName (PSZ) - input

Name of Print Device.

This can specify a print device name or a port name. If ulLevel is 0, it must be a port name. If ulLevel is 2 or 3, it must be a print device name.

ulLevel (ULONG) - input

Level of detail required.

This must be 0, 2 or 3.

pBuf (PVOID) - in/out

Buffer.

The returned contents of the buffer depend on the value specified in ulLevel as follows:

ulLevel Buffer Contents

0 A port name consisting of 9 characters, including a null terminator.

2 A print device name of type PSZ.

3 A PRDINFO3 structure.

cbBuf (ULONG) - input

Size, in bytes, of Buffer.

It must be greater than 0.

pcbNeeded (PULONG) - output

Size in bytes of available information.

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_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_DestNotFound (2152) The print device cannot be found.
• NERR_InvalidComputer (2351) The computer name is invalid.

Example

This sample code returns information for the device name that is entered at the command line. The local workstation is selected. The query is done for level 3 information.

#define INCL_BASE
#define INCL_DOSMEMMGR
#define INCL_SPL
#define INCL_SPLDOSPRINT
#define INCL_SPLERRORS

#include <os2.h>
#include <stdio.h>

INT main (argc, argv)
    INT argc;
    CHAR *argv[];
{
    SPLERR splerr;
    ULONG  cbBuf;
    ULONG  cbNeeded;
    ULONG  ulLevel;
    PSZ    pszComputerName;
    PSZ    pszPrintDeviceName;
    PVOID  pBuf;
    PPRDINFO3 pprd3;

    if (argc != 2)
    {
       printf("Syntax: sdqry DeviceName\n");
       DosExit(EXIT_PROCESS, 0);
    }

    pszComputerName = (PSZ)NULL;
    pszPrintDeviceName = argv[1];
    ulLevel = 3;
    splerr = SplQueryDevice(pszComputerName, pszPrintDeviceName,
                            ulLevel, (PVOID)NULL, 0L, &cbNeeded );
    if (splerr != NERR_BufTooSmall)
    {
       printf("SplQueryDevice Err=%ld, cbNeeded=%ld\n",splerr, cbNeeded);
       DosExit( EXIT_PROCESS , 0);
    }
    if (!DosAllocMem( &pBuf, cbNeeded,
                      PAG_READ|PAG_WRITE|PAG_COMMIT) ){
       cbBuf= cbNeeded ;
       splerr = SplQueryDevice(pszComputerName, pszPrintDeviceName,
                              ulLevel, pBuf, cbBuf, &cbNeeded);

       printf("SplQueryDevice Error=%ld, Bytes Needed=%ld\n", splerr,
                              cbNeeded);

       pprd3=(PPRDINFO3)pBuf;

       printf("Print Device info: name - %s\n", pprd3->pszPrinterName);
       printf("User Name      = %s\n", pprd3->pszUserName);
       printf("Logical Address= %s\n", pprd3->pszLogAddr);
       printf("Job ID         = %d\n", pprd3->uJobId);
       printf("Status         = %d\n", pprd3->fsStatus);
       printf("Status Comment = %s\n", pprd3->pszStatus);
       printf("Comment        = %s\n", pprd3->pszComment);
       printf("Drivers        = %s\n", pprd3->pszDrivers);
       printf("Time           = %d\n", pprd3->time);
       printf("Time Out       = %d\n", pprd3->usTimeOut);
       DosFreeMem(pBuf);
    }
    DosExit( EXIT_PROCESS, 0 );
    return (splerr);
}

Remarks

If ulLevel is 0, the port name in pBuf is truncated to 8 characters.

If ulLevel is 3, and pBuf cannot hold the entire PRDINFO3 structure, SplQueryDevice returns NERR_BufTooSmall (2123).

To obtain the size of buffer required, call SplQueryDevice with the required value of ulLevel and a NULL buffer. The number of bytes required is returned in pcbNeeded.

If no job is printing on the print device, bits 2-11 of fsStatus in the PRDINFO3 data structure are meaningless.

Related Functions

• SplCreateDevice
• SplDeleteDevice
• SplEnumDevice