Jump to content

PrtSet

From EDM2
Revision as of 19:21, 4 June 2020 by Ak120 (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

PrtSet sets printer device information.

Syntax

PrtSet(pszComputerName, pszDeviceName,
      ulType, ulCommand, pInData, cbInData);

Parameters

pszComputerName (PSZ) - input
Destination computer name or NULL for local printer.
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 set 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
Type of set and options.
Values are as follows:
TYPE_SHORT_WAIT(1) : Sends this 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 in order to set 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) : 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.
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_SEND_PASSTHRU (1h)
Printer-language-specific command will be issued to printer. See BIDI_SEND_PASSTHRU(1h) for input parameters.
BIDI_STARTJOB (2h)
Signals start of print job. See BIDI_STARTJOB (2h) for input parameters.
BIDI_ENDJOB (3h)
Signals end of print job. See BIDI_ENDJOB (3h) for input parameters.
BIDI_HOLDJOB (4h)
Holds printer job. See BIDI_HOLDJOB (4h) for input parameters.
BIDI_RELEASEJOB (5h)
Releases printer job. See BIDI_RELEASEJOB (5h) for input parameters.
BIDI_CANCELJOB (6h)
Cancels printer job. See BIDI_CANCELJOB (6h) for input parameters.
BIDI_INIT_PORTDRV (8h)
Initializes a port driver. See BIDI_INIT_PORTDRV (8h) for input parameters.
BIDI_RESET (9h)
Resets the printer. See BIDI_RESET(9h) for input parameters.
BIDI_SHUTDOWN (Ah)
Releases all threads waiting for this port. See BIDI_SHUTDOWN(Ah) for input parameters.
BIDI_INIT (Bh)
Sets printer in bidirectional mode. See BIDI_INIT(Bh) for input parameters.
BIDI_TERM (Ch)
Sets printer in unidirectional mode. See BIDI_TERM(Ch) for input parameters.
BIDI_RESPONSE_FMT (Dh)
Defines format of printer-to-host messages. See BIDI_RESPONSE_FMT(Dh) for input parameters.
BIDI_PACKET_SIZE (Eh)
Defines printer-to-host maximum packet size. See BIDI_PACKET_SIZE(Eh) for input parameters.
BIDI_INIT_PROTCNV (Fh)
Initializes the protocol converter for a port. See BIDI_INIT_PROTCNV(Fh) for input parameters.
BIDI_SET_SW (10h)
Tells port driver the BIDI software capabilities of the printer. See BIDI_SET_SW(10h) for input parameters.
BIDI_SET_PORTDRV (19h)
Stores port driver configuration. See BIDI_SET_PORTDRV(19h) for input parameters.
BIDI_START_PASSTHRU (1Ah)
Initiates a passthru session with the printer. See BIDI_START_PASSTHRU(1Ah) for input parameters.
BIDI_END_PASSTHRU (1Bh)
Terminates a passthru session with the printer. See BIDI_END_PASSTHRU(1Bh) for input parameters.
BIDI_NOTIFY_ENDJOBCONNECT (20h)
Notifies port driver that jobs are complete. See BIDI_NOTIFY_ENDJOBCONNECT(20h) for input parameters.
BIDI_NOTIFY_PORT_SELECTED (21h)
Notifies port driver that the printer is connected to a print queue. See BIDI_NOTIFY_PORT_SELECTED(21h) for input parameters.
BIDI_NOTIFY_PORT_RELEASED (22h)
Notifies port driver that the printer is no longer connected to a print queue. See BIDI_NOTIFY_PORT_RELEASED(22h) for input parameters.
BIDI_SET_DEVICE_ID (23h)
Tells spooler the printer's device ID. See BIDI_SET_DEVICE_ID(23h) for input parameters.
BIDI_ENABLE_ALERT (24h)
Enables printer alerts. See BIDI_ENABLE_ALERT(24h) for input parameters.
BIDI_DISABLE_ALERT (25h)
Disables printer alerts. See BIDI_DISABLE_ALERT(25h) for input parameters.
BIDI_ADD_VIRTUAL_PORT (26h)
Adds a virtual port. See BIDI_ADD_VIRTUAL_PORT(26h) for input parameters.
BIDI_DEL_VIRTUAL_PORT (27h)
Deletes a virtual port. See BIDI_DEL_VIRTUAL_PORT(27h) for input parameters.
BIDI_DEL_PORT (28h)
Indicates a spooler port has been deleted. See BIDI_DEL_PORT(28h) for input parameters.
0x00009000 - 0x00009FFF :Protocol-converter-specific commands.
0x0000B000 - 0x0000BFFF :Port-driver-specific commands.
pInData (PVOID) - input
Contains either a command sequence to pass to, or information required by, the printer.
If ulCommand is set to BIDI_SEND_PASSTHRU, pInData contains the command sequence to pass to the printer. The field will not be altered by the port driver or protocol converter unless ulType is set to TYPE_WITHOUT_WRAPPER.

_If ulCommand is not set to BIDI_SEND_PASSTHRU, pInData may contain information required by the command (see BIDI Command Structures and Command Flow for more information).

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

Returns

rc (ULONG) - returns
Return codes.
  • 0 Success
  • 1 (ERROR_INVALID_FUNCTION) : The command code is not supported. This 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) : 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 a 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.
  • 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.
  • 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 command BIDI_ENABLE_ALERT.
  • 211 (ERROR_INFO_NOT_AVAIL) : 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 may also 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.
  • 0x4009 (PMERR_SPL_SPOOLER_NOT_INSTALLED) : The spooler is not enabled, therefore bidirectional set requests are not supported.
  • 0x4011 (PMERR_SPL_INV_JOB_ID) : The job ID specified is not known.
  • 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.
  • Others : If pszComputerName is specified, other network errors may be returned.
Note
Currently, you cannot send more than 64KB of data from a spooler call over the network. Therefore, all data used in this API should be limited to less than 64KB for now.

Sample

#define INCL_SPL
#define INCL_SPLBIDI
#include <os2.h>

PSZ      pszComputerName;  /*  Destination computer name or NULL for local printer. */
PSZ      pszDeviceName;    /*  Port name on pszComputerName. */
ULONG    ulType;           /*  Type of set and options. */
ULONG    ulCommand;        /*  Generic command code. */
PVOID    pInData;          /*  Contains either a command sequence to pass to,
                               or information required by, the printer. */
ULONG    cbInData;         /*  Length of pInData, in bytes. */
ULONG    rc;               /*  Return codes. */

rc = PrtSet(pszComputerName, pszDeviceName,
       ulType, ulCommand, pInData, cbInData);

Remarks

A port driver must exist or this function returns ERROR_FILE_NOT_FOUND(2).

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