Jump to content

PrtQuery

From EDM2
Revision as of 01:00, 8 April 2020 by Ak120 (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

PrtQuery is called to get information about the print device.

Syntax

PrtQuery(pszComputerName, pszDeviceName, ulType, ulCommand,
         pInData, cbInData, pOutData, pcbOutData)

Parameters

pszComputerName (PSZ) - input
Destination computer name or NULL for local query.
Following is an example of a destination computer name: LS:\\SERVER
pszDeviceName (PSZ) - input
Port name on pszComputerName.
Following is an example of a port name: LPT1
This may also be the name of a local printer device or local print queue to allow presentation drivers to query printer characteristics during DevOpenDC or DevPostDeviceModes. The spooler will change the destination to be the port that is connected to either the printer device or the print queue.
ulType (ULONG) - input
Indicates 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 in order 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 updates 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 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 supported by the port driver or protocol converter, ERROR_INVALID_FUNCTION is returned.
The value of TYPE_CACHE_WAIT(5) may be used by the print object to issue BIDI_Q_STATUS, in order to get the current status of the printer without waiting to communicate with the printer.
ulCommand (ULONG) - input
Generic command code.
See BIDI Command Structures and Command Flow for contents of pInData and pOutData for each of the following commands.
Current commands are as follows:
BIDI_READ_PASSTHRU(8001h)
Wait 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 currently being sent to this port driver. 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_READ_ALERT(801Dh)
Read an extended alert. See BIDI_READ_ALERT(801Dh) for output parameter.
BIDI_Q_CONVERTER_INFO(8021h)
Return protocol converter information. See BIDI_Q_CONVERTER_INFO(8021h) for output parameter.
BIDI_Q_SPOOLER_VERSION(8022h)
Return spooler version information. See BIDI_Q_SPOOLER_VERSION(8022h) for output parameter.
BIDI_Q_STORAGE(8023h)
Return printer storage media. See BIDI_Q_STORAGE(8023h) for input and output parameters.
0x00009000 - 0x00009FFF
Protocol-converter-specific commands.
0x0000B000 - 0x0000BFFF
Port-driver-specific commands.
pInData (PVOID) - input
May contain information required by PrtQuery.
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, it will return a structure containing queried information for the command as defined in BIDI Command Structures and Command Flow.
pcbOutData (PULONG) - in/out
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 on exit.

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, or if the printer rejects the command.
  • 2 (ERROR_FILE_NOT_FOUND): The pszDeviceName given is not a valid port name with a port driver, a printer device name, or a printer queue name.
  • 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.
  • 53 (ERROR_BAD_NETPATH): The computer name specified is not available or is invalid.
  • 67 (ERROR_BAD_NET_NAME): The computer name cannot be found.
  • 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 supported. 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.
  • 0x4009 (PMERR_SPL_SPOOLER_NOT_INSTALLED): The spooler is not enabled, therefore bidirectional query requests are not supported.
  • 0x4011 (PMERR_SPL_INV_JOB_ID): No job is being actively sent to the printer port, therefore BIDI_Q_JOBID is not successful.
  • 0x403D (PMERR_SPL_CNV_NOT_INIT): The protocol converter or port driver has not been initialized for this port.
  • 0x403E(PMERR_SPL_INIT_IN_PROGRESS):Another thread is still processing BIDI_INIT_PORTDRV or the initial BIDI_Q_PORT for the given portname. The request should be tried again later.
  • 0x403F(PMERR_SPL_TYPE_NOT_AVAIL):The storage type requested for BIDI_Q_FONTS or BIDI_Q_STORAGE is not available in the printer.
  • 0x4041(PMERR_SPL_SESSION_TERM) :The passthru session has been terminated.
  • Others
If pszComputerName is specified, other network errors may be returned.
Note
Currently you cannot receive more than 64KB of data from a spooler call over the network. Therefore, all returned structures should be limited to less than 64KB for now.

Remarks

A port driver must exist or the PrtQuery call returns ERROR_FILE_NOT_FOUND(2).

Retrieved from "https://www.edm2.com/index.php?title=PrtQuery&oldid=73376"