SplPdOpen: Difference between revisions

Latest revision as of 19:08, 4 June 2020

SplPdOpen is an API exported by port drivers. It is called by PrtOpen to open a device for output. SplPdOpen returns a handle into the port driver to be used on the following calls:

SplPdOpen performs an implicit SplPdSet (BIDI_STARTJOB). The port driver should call PrtSet (BIDI_STARTJOB) during this API call.

Syntax

SplPdOpen(pszPortName, phDevice, pDeviceFlags, pPrtOpenStruct);

Parameters

pszPortName (PSZ) - input: Local port name.; Following is an example of a port name: LPT1
phDevice (PHFILE) - output: Returned port-driver handle for the device.
pDeviceFlags (PULONG) - output: Flag returns type of device being opened.; Values are as follows:

HANDTYPE_FILE 0x0000
HANDTYPE_DEVICE 0x0001
HANDTYPE_PIPE 0x0002
HANDTYPE_LPTDEVICE 0x0004
HANDTYPE_COMDEVICE 0x0008
HANDTYPE_NETWORK 0x8000

pPrtOpenStruct (PVOID) - input: Pointer to a parameter structure that describes the job being sent to the print device.; Some fields may be derived from the DevOpenDC() parameter DEVOPENSTRUC. See Data Types for details on the PRTOPENSTRUCT0 data structure.

Returns

rc (ULONG) - returns: Return codes.

0 Success
5 (ERROR_ACCESS_DENIED): Not authorized to open printer port.
8 (ERROR_NOT_ENOUGH_MEMORY): Not enough memory to satisfy request.
29 (ERROR_WRITE_FAULT): Failure attempting to write to the device. This could happen if a BIDI_START_JOB bracket is sent during open time, and the print device does not accept the start job command.
87 (ERROR_INVALID_PARAMETER): An invalid parameter was specified; most likely an invalid pointer was passed to PrtOpen.
99 (ERROR_DEVICE_IN_USE): Device is in use by another application.
240 (ERROR_VC_DISCONNECTED): Unable to connect to the remote printer.

Sample

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

PSZ       pszPortName;    /* Local port name. */
PHFILE    phDevice;       /* Returned port-driver handle for the device. */
PULONG    pDeviceFlags;   /* Flag returns type of device being opened. */
PVOID     pPrtOpenStruct; /* Pointer to a parameter structure that describes
                             the job being sent to the print device. */
ULONG     rc;             /* Return codes. */

rc = SplPdOpen(pszPortName, phDevice, pDeviceFlags, pPrtOpenStruct);

@@ Line 1: / Line 1: @@
-SplPdOpen is an API exported by port drivers. It is called by PrtOpen to open a device for output. SPlPDOpen returns a handle into the port driver to be used on the following calls:
+SplPdOpen is an API exported by port drivers. It is called by [[PrtOpen]] to open a device for output. SplPdOpen returns a handle into the port driver to be used on the following calls:
 *[[SplPdAbortDoc]]
 *[[SplPdClose]]
 *[[SplPdNewPage]]
 *[[SplPdResetAbort]]
 *[[SplPdWrite]]
+SplPdOpen performs an implicit [[SplPdSet]] (BIDI_STARTJOB). The port driver should call [[PrtSet]] (BIDI_STARTJOB) during this API call.
-SplPdOpen performs an implicit SplPdSet(BIDI_STARTJOB). The port driver should call PrtSet(BIDI_STARTJOB) during this API call.
 == Syntax ==
   SplPdOpen(pszPortName, phDevice, pDeviceFlags, pPrtOpenStruct);
 == Parameters ==
+;pszPortName (PSZ) - input: Local port name.
-; pszPortName (PSZ) - input
+: Following is an example of a port name: <tt>LPT1</tt>
-: Local port name.
+;phDevice (PHFILE) - output: Returned port-driver handle for the device.
+;pDeviceFlags (PULONG) - output: Flag returns type of device being opened.
-: Following is an example of a port name:
+:Values are as follows:
-    LPT1
+  HANDTYPE_FILE 0x0000
+  HANDTYPE_DEVICE 0x0001
-; phDevice (PHFILE) - output
+  HANDTYPE_PIPE 0x0002
-: Returned port-driver handle for the device.
+  HANDTYPE_LPTDEVICE 0x0004
+  HANDTYPE_COMDEVICE 0x0008
-; pDeviceFlags (PULONG) - output
+  HANDTYPE_NETWORK 0x8000
-: Flag returns type of device being opened.
+;pPrtOpenStruct (PVOID) - input: Pointer to a parameter structure that describes the job being sent to the print device.
+:Some fields may be derived from the DevOpenDC() parameter [[DEVOPENSTRUC]]. See Data Types for details on the PRTOPENSTRUCT0 data structure.
-Values are as follows:
-  HANDTYPE_FILE 0x0000
-  HANDTYPE_DEVICE 0x0001
-  HANDTYPE_PIPE 0x0002
-  HANDTYPE_LPTDEVICE 0x0004
-  HANDTYPE_COMDEVICE 0x0008
-  HANDTYPE_NETWORK 0x8000
-; pPrtOpenStruct (PVOID) - input : Pointer to a parameter structure that describes the job being sent to the print device.
-:Some fields may be derived from the DevOpenDC() parameter DEVOPENSTRUC. See Data Types for details on the PRTOPENSTRUCT0 data structure.
 == Returns ==
-; rc (ULONG) - returns : Return codes.
+;rc (ULONG) - returns: Return codes.
-* 0 Success
+*0 Success
-* 5(ERROR_ACCESS_DENIED)
+*5 (ERROR_ACCESS_DENIED): Not authorized to open printer port.
-:Not authorized to open printer port.
+*8 (ERROR_NOT_ENOUGH_MEMORY): Not enough memory to satisfy request.
-*8(ERROR_NOT_ENOUGH_MEMORY)
+*29 (ERROR_WRITE_FAULT): Failure attempting to write to the device. This could happen if a BIDI_START_JOB bracket is sent during open time, and the print device does not accept the start job command.
-:Not enough memory to satisfy request.
+*87 (ERROR_INVALID_PARAMETER): An invalid parameter was specified; most likely an invalid pointer was passed to PrtOpen.
-*29(ERROR_WRITE_FAULT)
+*99 (ERROR_DEVICE_IN_USE): Device is in use by another application.
-:Failure attempting to write to the device. This could happen if a BIDI_START_JOB bracket is sent during open time, and the print device does not accept the start job command.
+*240 (ERROR_VC_DISCONNECTED): Unable to connect to the remote printer.
-*87(ERROR_INVALID_PARAMETER)
-:An invalid parameter was specified; most likely an invalid pointer was passed to PrtOpen.
-*99(ERROR_DEVICE_IN_USE)
-:Device is in use by another application.
-* 240(ERROR_VC_DISCONNECTED)
-:Unable to connect to the remote printer.
 == Sample ==
@@ Line 58: / Line 41: @@
 #include <os2.h>
-PSZ       pszPortName;     /*  Local port name. */
+PSZ       pszPortName;    /* Local port name. */
-PHFILE    phDevice;        /*  Returned port-driver handle for the device. */
+PHFILE    phDevice;       /* Returned port-driver handle for the device. */
-PULONG    pDeviceFlags;    /*  Flag returns type of device being opened. */
+PULONG    pDeviceFlags;   /* Flag returns type of device being opened. */
-PVOID     pPrtOpenStruct;  /*  Pointer to a parameter structure that describes the job being sent to the print device. */
+PVOID     pPrtOpenStruct; /* Pointer to a parameter structure that describes
-ULONG     rc;              /*  Return codes. */
+                             the job being sent to the print device. */
+ULONG     rc;             /* Return codes. */
-rc = SplPdOpen(pszPortName, phDevice, pDeviceFlags,
+rc = SplPdOpen(pszPortName, phDevice, pDeviceFlags, pPrtOpenStruct);
-       pPrtOpenStruct);
 </pre>
 [[Category:Spl]]