Jump to content

DevEscape

From EDM2
Revision as of 22:25, 17 September 2017 by Ak120 (talk | contribs) (→Parameter)

This function allows applications to access facilities of a device not otherwise available through the API. Escapes are, in general, sent to the presentation driver and must be understood by it.

Syntax

DevEscape (hdc, lCode, lInCount, pbInData, plOutCount, pbOutData)

Parameter

hdc (HDC) - input
Device-context handle.
lCode (LONG) - input
Escape code.
If the device context is of type OD_QUEUED with a PM_Q_STD spool file, some escapes are sent to the presentation driver and others are recorded in the spool file (depending on the escape code). If the device context is of type OD_METAFILE, all escapes are metafiled. If the device context is of any type other than OD_QUEUED (with a PM_Q_STD spool file) or OD_METAFILE, all escapes are sent to the presentation driver.
The description for each standard escape specifies which of these categories the escape falls into.
Devices can define additional escape functions using user lCode values, that have the following ranges:
  • 32 768 through 40 959 Not metafiled and not recorded (sent to presentation driver for PM_Q_STD)
  • 40 960 through 49 151 Metafiled only (sent to presentation driver for PM_Q_STD)
  • 49 152 through 57 343 Metafiled and recorded (not sent to presentation driver) for PM_Q_STD
  • 57 344 through 65 535 Recorded only (not sent to presentation driver for PM_Q_STD).
The following escapes are defined:
DEVESC_QUERYESCSUPPORT
DEVESC_GETSCALINGFACTOR
DEVESC_STARTDOC
DEVESC_ENDDOC
DEVESC_ABORTDOC
DEVESC_NEWFRAME
DEVESC_RAWDATA
DEVESC_QUERYVIOCELLSIZES
DEVESC_SETMODE
lInCount (LONG) - input
Input data count.
Number of bytes of data in the pbInData buffer.
pbInData (PBYTE) - input
The input data required for this escape.
plOutCount (PLONG) - in/out
Output data count.
plOutCount is the number of bytes of data in the pbOutData buffer.
If data is returned in pbOutData, plOutCount is updated to the number of bytes of data returned.
pbOutData (PBYTE) - output
Output data.
pbOutData is a buffer that receives the output from this escape. If plOutCount is null, no data is returned.
lResult (LONG) - returns
Implementation error indicator:
DEVESC_ERROR Error
DEVESC_NOTIMPLEMENTED Escape not implemented for specified code
DEV_OK OK.

Remarks

The data fields for standard escapes are:

DEVESC_QUERYESCSUPPORT

Queries whether a particular escape is implemented by the presentation driver. The return value gives the result. This escape is not metafiled or recorded.

lInCount
Number of bytes pointed to by pbInData.
pbInData
The buffer contains an escape code value specifying the escape function to be checked.
plOutCount
Not used; can be set to 0.
pbOutData
Not used; can be set to null.

DEVESC_GETSCALINGFACTOR

Returns the scaling factors for the x and y axes of a printing device. For each scaling factor, an exponent of two is put in pbOutData. Thus, the value 3 is used if the scaling factor is 8.

Scaling factors are used by devices that cannot support graphics at the same resolution as the device resolution.

This escape is not metafiled or recorded.

lInCount
Not used; can be set to 0.
pbInData
Not used; can be set to null.
plOutCount
The number of bytes of data pointed to by pbOutData. On return, this is updated to the number of bytes returned.
pbOutData
The address of a SFACTORS structure, which on return contains the scaling factors for the x and y axes.

DEVESC_STARTDOC

Indicates that a new print job is starting. All subsequent output to the device context is spooled under the same job identifier until a DEVESC_ENDDOC occurs.

GpiAssociate must be issued to associate the presentation space with the device context before issuing this escape.

This escape is metafiled but not recorded.

lInCount
Number of bytes pointed to by pbInData.
pbInData
The buffer contains a null-terminated string, specifying the name of the document.
plOutCount
Not used; can be set to 0.
pbOutData
Not used; can be set to null.

DEVESC_ENDDOC

Ends a print job started by DEVESC_STARTDOC. This escape is metafiled but not recorded.

lInCount
Not used; can be set to 0.
pbInData
Not used; can be set to null.
plOutCount
Set equal to 2.
pbOutData
The buffer contains a USHORT specifying the job identifier if a spooler print job is created.

DEVESC_ABORTDOC

Aborts the current job, erasing everything the application has written to the device since the last DEVESC_STARTDOC, including the DEVESC_STARTDOC. This escape is metafiled but not recorded.

lInCount
Not used; can be set to 0
pbInData
Not used; can be set to null
plOutCount
Not used; can be set to 0
pbOutData
Not used; can be set to null.

DEVESC_NEWFRAME

Signals when an application has finished writing to a page and wants to start a new page. It is similar to GpiErase processing for a screen device context, and causes a reset of the attributes. This escape is used with a printer device to advance to a new page. This escape is metafiled and recorded.

lInCount
Not used; can be set to 0
pbInData
Not used; can be set to null
plOutCount
Not used; can be set to 0
pbOutData
Not used; can be set to null.

DEVESC_RAWDATA

Allows an application to send data directly to a presentation driver. For example, in the case of a printer driver, this could be a printer data stream. If DEVESC_RAWDATA is mixed with other data (such as GPI data) being sent to the same page of a device context, the results are unpredictable and depend upon the action taken by the presentation driver. For example, a presentation driver might ignore GPI data if DEVESC_RAWDATA is mixed with it on the same page. In general, DEVESC_RAWDATA should be sent either to a separate page (using the DEVESC_NEWFRAME escape to obtain a new page) or to a separate document (using the DEVESC_STARTDOC and DEVESC_ENDDOC escapes to create a new document). This escape is metafiled and recorded.

lInCount
Number of bytes pointed to by pbInData pbInData Pointer to the raw data plOutCount Not used; can be set to 0 pbOutData Not used; can be set to null.

DEVESC_QUERYVIOCELLSIZES

Returns the VIO cell sizes supported by the presentation driver.

This escape is not metafiled or recorded.

lInCount
Not used; can be set to 0
pbInData
Not used; can be set to null.
plOutCount
The number of bytes of data pointed to by pbOutData. It must be an even multiple of the size in bytes of the LONG data type. On return, this is updated to the number of bytes

returned.

pbOutData
The address of a buffer, which on return contains a VIOSIZECOUNT structure, immediately followed by count copies of a VIOFONTCELLSIZE structure.
If plOutCount is less than the size of a LONG data type, plOutCount is updated to zero,

and nothing is returned in the buffer pointed to by pbOutData.

If plOutCount is equal to the size of a LONG data type, pbOutData returns the number of

VIO cell sizes that can be returned by this escape. The buffer pointed to by pbOutData is updated so that maxcount is the number of VIO cell sizes that can be returned.

If plOutCount is greater than the size of a LONG data type, pbOutData returns the VIO cell

sizes that are supported. The buffer pointed to by pbOutData is updated so that:

  • maxcount is the number of VIO cell sizes that can be returned
  • count is the number of VIO cell sizes returned (may be zero if plOutCount is equal to twice the size of a LONG data type)
  • count copies of a VIOFONTCELLSIZE structure are returned.

DEVESC_SETMODE

Sets the printer into a particular mode. It is optional for printer drivers to support this escape, but those that do support it need to be aware of the code page of any built-in fonts. For example, if only code page 437 is built in, it is used if 437 is requested by DEVESC_SETMODE; however, if code page 865 is requested, a suitable code page/font could be downloaded. This escape is metafiled and recorded.

lInCount
Number of bytes pointed to by pbInData
pbInData
Buffer contains an ESCSETMODE structure
plOutCount
Not used; can be set to 0
pbOutData
Not used; can be set to null.

Errors

Possible returns from WinGetLastError

  • PMERR_INV_ESC_CODE (0x206D) - An invalid escape code was used in a call to DevEscape.
  • PMERR_INV_HDC (0x207C) - An invalid device-context handle or (micro presentation space) presentation-space handle was specified.
  • PMERR_INV_LENGTH_OR_COUNT (0x2092) - An invalid length or count parameter was specified.
  • PMERR_ESC_CODE_NOT_SUPPORTED (0x202B) - The code specified with DevEscape is not supported by the target device driver.
  • PMERR_INV_ESCAPE_DATA (0x206E) - An invalid data parameter was specified with DevEscape.

Related Functions

  • GpiAssociate (for DEVESC_STARTDOC)
  • GpiErase (for DEVESC_NEWFRAME)

Graphic Elements and Orders

DevEscape functions generate orders only when metafiling. Order: GEESCP

Example Code

This example uses DevEscape to access facilities of a device that would otherwise be unavailable through the normal Device API set. Here, a new page in a print job is started. 

#define INCL_DEV  /* Device Function definitions  */
#include <os2.h>

LONG  lResult;    /* Error code or not implemented warning code */
HDC   hdc;        /* Device-context handle                */
LONG  plOutCount; /* length of output buffer(input), number of bytes returned(output) */
PBYTE pbOutData;  /* output buffer                        */

/* for the NEWFRAME, input and output buffers are not used, so set the buffer lengths
   to zero(0) and set the buffers to NULL */
plOutCount = 0;
pbOutData = NULL;

lResult = DevEscape(hdc, DEVESC_NEWFRAME, 0L, NULL, &plOutCount,pbOutData);
Retrieved from "https://www.edm2.com/index.php?title=DevEscape&oldid=50060"