Jump to content

SplProtSendCmd

From EDM2
Revision as of 14:58, 12 December 2022 by Ak120 (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

SplProtSendCmd is an API exported by protocol converters. It is called by PrtQuery or PrtSet to convert generic commands into BIDI protocol-specific commands to send to the printer.

Syntax

SplProtSendCmd(pszPortName, ulType, ulCommand,
      pfnPdSendCmd, pfnBaseProtSendCmd, pInData,
      cbInData, pOutData, pcbOutData);

Parameters

pszPortName (PSZ) - input
Port name.
Following is an example of a port name: LPT1
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 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 or sends passthru or alert information without any packet wrapper around it.
This is useful for BIDI_READ_PASSTHRU and BIDI_SEND_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.
If BIDI_SEND_PASSTHRU is used without this value, the calling application must have already wrapped the passthru data.
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_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.

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_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_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_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_STORAGE(8023h) - Return printer storage media. See BIDI_Q_STORAGE(8023h) for input and output parameters.
0x00009000 - 0x00009FFF - Protocol-converter-specific commands.
pfnPdSendCmd (PFN) - input
Port driver send-routine address.
This is the address of a function in the port driver that will be called to send commands to the printer. Only the BIDI converters will call this function. SplProtSendCmd calls SplPdSendCmd, which sends protocol-specific commands to the printer.
pfnBaseProtSendCmd (PFN) - input
Base protocol converter address for ProtSendCmd routine.
This is NULL unless the protocol converter is an extension to the base protocol converter. If not NULL, the extension protocol converter can call the base converter at this address to let the base converter process the command.
pInData (PVOID) - input
May contain information required by PrtQuery and PrtSet.
cbInData (ULONG) - input
Length of information in pInData, in bytes.
pOutData (PVOID) - output
Return buffer.
If successful, this returns a structure as defined by PrtQuery and PrtSet. The format will be protocol-dependent.
pcbOutData (PULONG) - output
Points to the length of the output buffer.
On entry, this is set to the length of the output 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, or if the printer rejects the command.
  • 2 (ERROR_FILE_NOT_FOUND) - The pszPortName given is not a valid port 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 command sequence.
  • 87 (ERROR_INVALID_PARAMETER) - An invalid buffer given.
  • 117 (ERROR_INVALID_CATEGORY) - The protocol converter does not handle the category given with command BIDI_ENABLE_ALERT.
  • 186 (ERROR_INVALID_FLAG_NUMBER) - The protocol converter does not understand one of the core alert types set with BIDI_ENABLE_ALERT.
  • 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 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

#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. */
PFN       pfnPdSendCmd;        /*  Port driver send-routine address. */
PFN       pfnBaseProtSendCmd;  /*  Base protocol converter address for ProtSendCmd routine. */
PVOID     pInData;             /*  May contain information required by PrtQuery and PrtSet. */
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 = SplProtSendCmd(pszPortName, ulType, ulCommand,
       pfnPdSendCmd, pfnBaseProtSendCmd, pInData,
       cbInData, pOutData, pcbOutData);

Remarks

The protocol converter will call pfnPdSendCmd to send any commands to the printer. The protocol converter will hold the caller of SplProtSendCmd until the requested information is returned by the printer.

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