Difference between revisions of "SplPdSet"

From EDM2
Jump to: navigation, search
m
m
 
Line 1: Line 1:
SplPdSet is an API exported by port drivers. It is called by PrtSet to set printer device information.
+
SplPdSet is an API exported by port drivers. It is called by [[PrtSet]] to set printer device information.
  
 
== Syntax ==
 
== Syntax ==
Line 8: Line 8:
 
:Following is an example of a port name: LPT1
 
:Following is an example of a port name: LPT1
 
:This will be a locally defined port name.
 
:This will be a locally defined port name.
;ulType (ULONG) - input : Type of query and options.  
+
;ulType (ULONG) - input : Type of query and options.
 
:Values are as follows:
 
:Values are as follows:
:TYPE_SHORT_WAIT(1) - Sends information via a communications channel with the printer that can be used while a job is being sent to the printer.  
+
:TYPE_SHORT_WAIT(1) - Sends 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 sent using this type of channel (for instance, if a PJL command is required to get this information), ERROR_INFO_NOT_AVAIL is returned.
 
::An example would be using NPAP or SNMP. If the requested information cannot be sent 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) - Sends 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.
 
:TYPE_LONG_WAIT(2) - Sends 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.
Line 21: Line 21:
  
 
;ulCommand (ULONG) - input : Generic command code.
 
;ulCommand (ULONG) - input : Generic command code.
:The BIDI protocol converter may be called to generate protocol-specific command data to satisfy set requests. See BIDI Command Structures and Command Flow for contents of pInData and pOutData for each of the following commands.  
+
:The BIDI protocol converter may be called to generate protocol-specific command data to satisfy set 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:
 
Current [[command values]] are as follows:
*BIDI_SEND_PASSTHRU(8001h): Printer protocol-specific command will be issued to the printer.  
+
*BIDI_SEND_PASSTHRU (8001h): Printer protocol-specific command will be issued to the printer.  
*BIDI_STARTJOB(2h): Signals start of print job.
+
*BIDI_STARTJOB (2h): Signals start of print job.
*BIDI_ENDJOB(3h): Signals end of print job.
+
*BIDI_ENDJOB (3h): Signals end of print job.
*BIDI_HOLDJOB(4h): Holds printer job.
+
*BIDI_HOLDJOB (4h): Holds printer job.
*BIDI_RELEASEJOB(5h): Releases printer job.
+
*BIDI_RELEASEJOB (5h): Releases printer job.
*BIDI_CANCELJOB(6h): Cancels printer job.
+
*BIDI_CANCELJOB (6h): Cancels printer job.
*BIDI_INIT_PORTDRV(8h): Initializes a port driver.
+
*BIDI_INIT_PORTDRV (8h): Initializes a port driver.
*BIDI_RESET(9h): Resets the printer.
+
*BIDI_RESET (9h): Resets the printer.
*BIDI_SHUTDOWN(Ah): Releases all threads waiting for this port. Used to shut down a printer port. Sent to the protocol converter before being sent to the port driver.
+
*BIDI_SHUTDOWN (Ah): Releases all threads waiting for this port. Used to shut down a printer port. Sent to the protocol converter before being sent to the port driver.
*BIDI_INIT(Bh): Sets printer in BIDI mode. Changes printer from unidirectional to bidirectional. Does not call the protocol converter.
+
*BIDI_INIT (Bh): Sets printer in BIDI mode. Changes printer from unidirectional to bidirectional. Does not call the protocol converter.
*BIDI_TERM(Ch): Sets printer in unidirectional mode. Changes printer from bidirectional to unidirectional. Does not call the protocol converter.
+
*BIDI_TERM (Ch): Sets printer in unidirectional mode. Changes printer from bidirectional to unidirectional. Does not call the protocol converter.
*BIDI_RESPONSE_FMT(Dh): Defines the format of printer-to-host messages.
+
*BIDI_RESPONSE_FMT (Dh): Defines the format of printer-to-host messages.
*BIDI_PACKET_SIZE(Eh): Defines printer-to-host maximum packet size.
+
*BIDI_PACKET_SIZE (Eh): Defines printer-to-host maximum packet size.
*BIDI_SET_PORTDRV(19h): Sets port driver configuration.
+
*BIDI_SET_PORTDRV (19h): Sets port driver configuration.
*BIDI_START_PASSTHRU(1Ah): Initiates a passthru session with the printer.
+
*BIDI_START_PASSTHRU (1Ah): Initiates a passthru session with the printer.
*BIDI_END_PASSTHRU(1Bh): Terminates a passthru session with the printer.
+
*BIDI_END_PASSTHRU (1Bh): Terminates a passthru session with the printer.
*BIDI_NOTIFY_ENDJOBCONNECT(20h): Notifies port driver that jobs are complete.
+
*BIDI_NOTIFY_ENDJOBCONNECT (20h): Notifies port driver that jobs are complete.
*BIDI_NOTIFY_PORT_SELECTED(21h): Notifies port driver that printer is connected to print queue.
+
*BIDI_NOTIFY_PORT_SELECTED (21h): Notifies port driver that printer is connected to print queue.
*BIDI_NOTIFY_PORT_RELEASED(22h): Notifies port driver that printer is not connected to print queue.
+
*BIDI_NOTIFY_PORT_RELEASED (22h): Notifies port driver that printer is not connected to print queue.
*BIDI_SET_DEVICE_ID(23h): Tells port driver the printer's device ID.
+
*BIDI_SET_DEVICE_ID (23h): Tells port driver the printer's device ID.
*BIDI_ENABLE_ALERT(24h): Enables printer alerts.
+
*BIDI_ENABLE_ALERT (24h): Enables printer alerts.
*BIDI_DISABLE_ALERT(25h): Disables printer alerts.
+
*BIDI_DISABLE_ALERT (25h): Disables printer alerts.
*BIDI_ADD_VIRTUAL_PORT(26h): Adds a virtual port.
+
*BIDI_ADD_VIRTUAL_PORT (26h): Adds a virtual port.
*BIDI_DEL_VIRTUAL_PORT(27h): Deletes a virtual port.
+
*BIDI_DEL_VIRTUAL_PORT (27h): Deletes a virtual port.
*BIDI_DEL_PORT(28h): Indicates a spooler port has been deleted.  
+
*BIDI_DEL_PORT (28h): Indicates a spooler port has been deleted.
*0x0000B000 - 0x0000BFFF:Port-driver-specific commands.  
+
*0x0000B000 - 0x0000BFFF:Port-driver-specific commands.
 
+
 
;pInData (PVOID) - input: May contain information required by SplPdSet.
 
;pInData (PVOID) - input: May contain information required by SplPdSet.
  

Latest revision as of 17:19, 22 October 2021

SplPdSet is an API exported by port drivers. It is called by PrtSet to set printer device information.

Syntax

SplPdSet(pszPortName, ulType, ulCommand, pInData, cbInData)

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_SHORT_WAIT(1) - Sends 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 sent 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) - Sends 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_WITHOUT_WRAPPER(4) - Indicates the information being sent does not have any packet wrapper around it.
This is useful for 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 sending a PostScript query to the printer, and the NPAP protocol converter adds the necessary NPAP wrapper before transmitting the data to the printer.
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_SEND_PASSTHRU, ERROR_INVALID_PARAMETER is returned.

ulCommand (ULONG) - input 
Generic command code.
The BIDI protocol converter may be called to generate protocol-specific command data to satisfy set 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_SEND_PASSTHRU (8001h): Printer protocol-specific command will be issued to the printer.
  • BIDI_STARTJOB (2h): Signals start of print job.
  • BIDI_ENDJOB (3h): Signals end of print job.
  • BIDI_HOLDJOB (4h): Holds printer job.
  • BIDI_RELEASEJOB (5h): Releases printer job.
  • BIDI_CANCELJOB (6h): Cancels printer job.
  • BIDI_INIT_PORTDRV (8h): Initializes a port driver.
  • BIDI_RESET (9h): Resets the printer.
  • BIDI_SHUTDOWN (Ah): Releases all threads waiting for this port. Used to shut down a printer port. Sent to the protocol converter before being sent to the port driver.
  • BIDI_INIT (Bh): Sets printer in BIDI mode. Changes printer from unidirectional to bidirectional. Does not call the protocol converter.
  • BIDI_TERM (Ch): Sets printer in unidirectional mode. Changes printer from bidirectional to unidirectional. Does not call the protocol converter.
  • BIDI_RESPONSE_FMT (Dh): Defines the format of printer-to-host messages.
  • BIDI_PACKET_SIZE (Eh): Defines printer-to-host maximum packet size.
  • BIDI_SET_PORTDRV (19h): Sets port driver configuration.
  • BIDI_START_PASSTHRU (1Ah): Initiates a passthru session with the printer.
  • BIDI_END_PASSTHRU (1Bh): Terminates a passthru session with the printer.
  • BIDI_NOTIFY_ENDJOBCONNECT (20h): Notifies port driver that jobs are complete.
  • BIDI_NOTIFY_PORT_SELECTED (21h): Notifies port driver that printer is connected to print queue.
  • BIDI_NOTIFY_PORT_RELEASED (22h): Notifies port driver that printer is not connected to print queue.
  • BIDI_SET_DEVICE_ID (23h): Tells port driver the printer's device ID.
  • BIDI_ENABLE_ALERT (24h): Enables printer alerts.
  • BIDI_DISABLE_ALERT (25h): Disables printer alerts.
  • BIDI_ADD_VIRTUAL_PORT (26h): Adds a virtual port.
  • BIDI_DEL_VIRTUAL_PORT (27h): Deletes a virtual port.
  • BIDI_DEL_PORT (28h): Indicates a spooler port has been deleted.
  • 0x0000B000 - 0x0000BFFF:Port-driver-specific commands.
pInData (PVOID) - input
May contain information required by SplPdSet.

If BIDI_SEND_PASSTHRU is set, this parameter contains the command sequence to pass to the printer and will not be altered by the port driver.

If BIDI_SEND_PASSTHRU is not set, this parameter may contain information required by SplPdSet. See BIDI Command Structures and Command Flow for specific information definitions.

cbInData (ULONG) - input
Length of information in pInData, in bytes.

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 set 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.
640 ERROR_TIMEOUT The set command was not able to be sent to the printer within the time allotted.
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.
0x1403 PMERR_ALREADY_INITIALIZED The port driver has already been initialized for the port.
0x4005 PMERR_SPL_INV_HSPL Not currently in a passthru session.
0x4011 PMERR_SPL_INV_JOB_ID The Job ID is not known.
0x403D PMERR_SPL_CNV_NOT_INIT The protocol converter or port driver has not been initialized for this port.

Example Code

#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 SplPdSet. */
ULONG    cbInData;    /* Length of information in pInData, in bytes. */
ULONG    rc;          /* Return codes. */

rc = SplPdSet(pszPortName, ulType, ulCommand, pInData, cbInData);