View source for SplPdQuery

SplPdQuery is an API exported by poirt drivers. It is called by PrtQuery to acquire information about the print device.

== Syntax ==
 SplPdQuery(pszPortName, ulType, ulCommand, pInData, cbInData, pOutData, pcbOutData)

== Parameters ==
;pszPortName (PSZ) - input: Port name.
:Following is an example of a port name: <tt>LPT1</tt>
:This will be a locally defined port name.
;ulType (ULONG) - input:Type of query and options.
:Values are as follows: 
::TYPE_CACHE_ONLY(0) 
:::Returns information from the protocol converter or port driver's cache only. Does not send anything to the printer.
:::If the requested information is not available, ERROR_INFO_NOT_AVAIL is returned. The caller should reissue the command with a different ulType value.
::TYPE_SHORT_WAIT(1)
:::Returns information via a communications channel with the printer that can be used while a job is being sent to the printer.
:::An example would be using NPAP or SNMP. If the requested information cannot be returned using this type of channel (for instance, if a PJL command is required to get this information), ERROR_INFO_NOT_AVAIL is returned.
::TYPE_LONG_WAIT(2)
:::Returns information using any necessary communications channel with the printer, even if the request has to wait for the current job being sent to the printer to complete.
:::If the printer supports only one command channel, and this channel can be used while a job is being sent to the printer, TYPE_SHORT_WAIT(1) and TYPE_LONG_WAIT(2) will behave in the same way.
::TYPE_CACHE_UPDATE(3)
:::Returns information from the protocol converter or port driver's cache and also update the cache in the background.
:::This is an optional type of query to support and, if it is not supported, will return ERROR_INVALID_FUNCTION.
:::If the requested information is not available in the cache, ERROR_INFO_NOT_AVAIL is returned. The caller should reissue the command with a different ulType value.
::TYPE_WITHOUT_WRAPPER(4)
:::Returns passthru or alert information without any packet wrapper around it.
::This is useful for BIDI_READ_PASSTHRU as it allows an application to send and receive printer-interpreter language commands without having to know the format of the BIDI protocol's data wrappers. An example would be removing the NPAP wrapper before returning Postscript response data to an application.
::If BIDI_READ_PASSTHRU is used without this value, the calling application requests the data as the printer returns it, possibly with any data wrappers.
::Note: If this value is used with any command other than BIDI_READ_PASSTHRU, ERROR_INVALID_PARAMETER is returned.
::TYPE_CACHE_WAIT(5)
::Returns information from the protocol converter or port driver's cache only. If the data is not available in the cache, use any mechanism available to get the information.
::If TYPE_CACHE_WAIT(5) is not be supported by the port driver or protocol converter, ERROR_INVALID_PARAMETER is returned.
::The value of TYPE_CACHE_WAIT(5) may be used by the print object to issue BIDI_Q_STATUS, to get the current status of the printer without waiting to communicate with the printer.
;ulCommand (ULONG) - input: Generic command code.
:For all commands except BIDI_WAIT_ALERT and BIDI_Q_PORT, the BIDI protocol converter may be called to generate protocol-specific command data to satisfy query requests. See BIDI Command Structures and Command Flow for contents of pInData and pOutData for each of the following commands.
:Current command values are as follows:
:;BIDI_READ_PASSTHRU (8001h)
::Waits for any response from printer. This must be done from within a passthru session.
::See BIDI_START_PASSTHRU(1Ah) for more details. See BIDI_READ_PASSTHRU(8001h) for input and output parameters.
:;BIDI_Q_PORT (800Bh)
::Query BIDI capabilities of the port. See BIDI_Q_PORT(800Bh) for input and output parameters.
:;BIDI_Q_SW (800Ch)
::Query BIDI software capabilities. See BIDI_Q_SW(800Ch) for input and output parameters.
:;BIDI_Q_DEVICE (800Dh)
::Query printer device characteristics. See BIDI_Q_DEVICE(800Dh) for input and output parameters. 
:;BIDI_Q_INTERPRETER(800Eh) 
::Query interpreters available in the printer. See BIDI_Q_INTERPRETER(800Eh) for input and output parameters. 
:;BIDI_Q_INPUTBINS(800Fh) 
::Query input bins. See BIDI_Q_INPUTBINS(800Fh) for input and output parameters.
:;BIDI_Q_OUTPUTBINS(8010h)
::Query output bins. See BIDI_Q_OUTPUTBINS(8010h) for input and output parameters.
:;BIDI_Q_FONTS(8012h)
::Query fonts for a particular interpreter. See BIDI_Q_FONTS(8012h) for input and output parameters.
:;BIDI_Q_JOBS_COMPLETE(8013h)
Query list of completed jobs. See BIDI_Q_JOBS_COMPLETE(8013h) for input and output parameters.
:;BIDI_Q_JOBS_QUEUED(8014h)
Query list of queued jobs. See BIDI_Q_JOBS_QUEUED(8014h) for input and output parameters.
:;BIDI_Q_STATUS(8015h)
::Query current status of the print device. See BIDI_Q_STATUS(8015h) for input and output parameters.
:;BIDI_WAIT_ALERT(8016h)
::Wait for unsolicited alerts. See BIDI_WAIT_ALERT(8016h) for input and output parameters.
:;BIDI_Q_JOBID(8017h)
::Query the printer Job ID associated with the active PrtOpen/SplPdOpen handle. See BIDI_Q_JOBID(8017h) for input and output parameters.
:;BIDI_Q_RESPONSE_FMT(8018h)
::Return format of printer-to-host messages. See BIDI_Q_RESPONSE_FMT(8018h) for input and output parameters.
:;BIDI_Q_PORTDRV(8019h)
::Query port driver's configuration for the port. See BIDI_Q_PORTDRV(8019h) for input and output parameters.
::This command does not go to the printer or protocol converter.
:;BIDI_Q_STORAGE(8023h)
::Query storage media in printer. See BIDI_Q_STORAGE(8023h) for input and output parameters.
:::0x0000B000 - 0x0000BFFF 
:::Port-driver-specific commands. 

;pInData (PVOID) - input:May contain information required by SplPdQuery.
:See BIDI Command Structures and Command Flow for specific information definitions.
;cbInData (ULONG) - input:Length of information in pInData, in bytes. 
;pOutData (PVOID) - output:Return buffer.
:Format of buffer depends on ulCommand. For BIDI_READ_PASSTHRU, this will contain BIDI protocol-specific response data and will not be interpreted by the BIDI protocol converter. However, if ulType is TYPE_WITHOUT_WRAPPER, any protocol data wrapper is removed before returning the printer-specific information.
:For other commands, see BIDI Command Structures and Command Flow for the structure returned.
;pcbOutData (PULONG) - output: Points to the length of the output buffer.
:On entry, this is set to the length of the buffer passed in. On exit, it is updated with the length of data available.
:If ERROR_MORE_DATA(234) or NERR_BufTooSmall(2123) is set, this field has the buffer size required to get all available information.

== Returns ==
; rc (ULONG) - returns : Return codes.
* 0 Success
* 1(ERROR_INVALID_FUNCTION) : The command code is not supported. This lack of support may occur if a new command is sent to an old spooler, port driver, or protocol converter.
* 2(ERROR_FILE_NOT_FOUND) : The pszPortName given is not a valid port name configured for this port driver.
* 5(ERROR_ACCESS_DENIED) : Not authorized to access printer port.
* 8(ERROR_NOT_ENOUGH_MEMORY) : Not enough memory to satisfy request.
* 29(ERROR_WRITE_FAULT) : Failure attempting to write to the device. The printer might not have received the query request.
* 87(ERROR_INVALID_PARAMETER) : An invalid parameter was specified; most likely an invalid buffer pointer was given.
* 211(ERROR_INFO_NOT_AVAIL) : The requested information is not available in the protocol converter cache, or the request cannot be sent with the given ulType value. The request should be reissued with a different ulType value.
* 234(ERROR_MORE_DATA) : Part of the information requested was returned, but there was not enough room for all the data. *pcbOutData contains the size of buffer needed to retrieve all the query response data.
* 640(ERROR_TIMEOUT) The printer response was not received within the time allotted. The caller may reissue the query, at which time the information might be available.
* 683(ERROR_BIDI_NO_SUPPORT) : The printer is not in bidirectional mode, therefore query requests are not honored. The port also may be in the process of being shut down.
* 2123(NERR_BufTooSmall) : No information was returned because the output buffer was too small. *pcbOutData contains the size of buffer needed to retrieve all the query response data.
* 0x4005(PMERR_SPL_INV_HSPL) : Not currently in a passthru session.
* 0x4011(PMERR_SPL_INV_JOB_ID) : No job is being actively sent to the printer port, therefore BIDI_Q_JOBID is not successful.
* 0x4041(PMERR_SPL_SESSION_TERM) : The passthru session has been terminated.
* 0x403D(PMERR_SPL_CNV_NOT_INIT) : The protocol converter or port driver has not been initialized for this port.
* 0x403F(PMERR_SPL_TYPE_NOT_AVAIL) : The storage type requested for BIDI_Q_FONTS or BIDI_Q_STORAGE is not available in the printer.

== Sample ==
<pre>
#define INCL_SPL
#define INCL_SPLBIDI
#include <os2.h>

PSZ       pszPortName;  /*  Port name. */
ULONG     ulType;       /*  Type of query and options. */
ULONG     ulCommand;    /*  Generic command code. */
PVOID     pInData;      /*  May contain information required by SplPdQuery. */
ULONG     cbInData;     /*  Length of information in pInData, in bytes. */
PVOID     pOutData;     /*  Return buffer. */
PULONG    pcbOutData;   /*  Points to the length of the output buffer. */
ULONG     rc;           /*  Return codes. */

rc = SplPdQuery(pszPortName, ulType, ulCommand,
       pInData, cbInData, pOutData, pcbOutData);
</pre>

[[Category:Spl]]