Windows GDI
Escape
The Escape function enables applications to access capabilities of a particular device not directly available through GDI. Escape calls made by an application are translated and sent to the driver.
int Escape(
HDC hdc, // handle to DC
int nEscape, // escape function
int cbInput, // size of input structure
LPCSTR lpvInData, // input structure
LPVOID lpvOutData // output structure
);
Parameters
- hdc
- [in] Handle to the device context.
- nEscape
- [in] Specifies the escape function to be performed. This parameter must be one of the predefined escape values listed in the Remarks section. Use the ExtEscape function if your application defines a private escape value.
- cbInput
- [in] Specifies the number of bytes of data pointed to by the lpvInData parameter. This can be 0.
- lpvInData
- [in] Pointer to the input structure required for the specified escape.
- lpvOutData
- [out] Pointer to the structure that receives output from this escape. This parameter should be NULL if no data is returned.
Return Values
If the function succeeds, the return value is greater than zero, except with the QUERYESCSUPPORT printer escape, which checks for implementation only. If the escape is not implemented, the return value is zero.
If the function fails, the return value is a system error code.
Windows NT/2000/XP: To get extended error information, call GetLastError.
Errors
If the function fails, the return value is one of the following values.
| Value | Meaning |
| SP_ERROR | General error. If SP_ERROR is returned, Escape may set the last error code to:
ERROR_INVALID_PARAMETER
ERROR_DISK_FULL
ERROR_NOT_ENOUGH_MEMORY
ERROR_PRINT_CANCELLED |
| SP_OUTOFDISK | Not enough disk space is currently available for spooling, and no more space will become available. |
| SP_OUTOFMEMORY | Not enough memory is available for spooling. |
| SP_USERABORT | The user terminated the job through Print Manager. |
Remarks
The effect of passing 0 for cbInput will depend on the value of nEscape and on the driver that is handling the escape.
Of the original printer escapes, only the following can be used.
| Escape | Description |
| QUERYESCSUPPORT | Determines whether a particular escape is implemented by the device driver. |
| PASSTHROUGH | Allows the application to send data directly to a printer. |
The following printer escapes are obsolete. They are provided only for compatibility with 16-bit versions of Windows.
| Escape | Description |
| ABORTDOC | Stops the current print job and erases everything the application has written to the device since the last ENDDOC escape.
This escape has been superseded by AbortDoc. |
| ENDDOC | Ends a print job started by the STARTDOC escape.
This is superseded by EndDoc. |
| GETPHYSPAGESIZE | Retrieves the physical page size and copies it to the specified location.
This escape has been superseded by PHYSICALWIDTH and PHYSICALHEIGHT in GetDeviceCaps. |
| GETPRINTINGOFFSET | Retrieves the offset from the upper-left corner of the physical page where the actual printing or drawing begins.
This escape has been superseded by PHYSICALOFFSETX and PHYSICALOFFSETY in GetDeviceCaps. |
| GETSCALINGFACTOR | Retrieves the scaling factors for the x-axis and the y-axis of a printer.
This escape has been superseded by SCALINGFACTORX and SCALINGFACTORY in GetDeviceCaps. |
| NEWFRAME | Informs the printer that the application has finished writing to a page.
This escape has been superseded by EndPage which ends a page. Unlike NEWFRAME, EndPage is always called after printing a page. |
| NEXTBAND | Informs the printer that the application has finished writing to a band.
Band information is no longer used. |
| SETABORTPROC | Sets the Abort function for a print job.
This escape has been superseded by SetAbortProc. |
| SETCOPYCOUNT | Sets the number of copies.
This escape has been superseded by DocumentProperties or PrinterProperties. |
| STARTDOC | Informs a printer driver that a new print job is starting.
This escape has been superseded by StartDoc. |
In addition, the StartPage function is used to prepare the printer driver to receive data.
Example Code
For an example, see Creating a Printer Device Context.
Windows NT/2000/XP/Vista: Included in Windows NT 3.1 and later.
Windows 95/98/Me: Included in Windows 95 and later.
Header: Declared in Wingdi.h; include Windows.h.
Library: Use Gdi32.lib.
See Also
Printing and Print Spooler Overview, Printing and Print Spooler Functions, AbortDoc,DocumentProperties, EndDoc, EndPage, ExtEscape, GetDeviceCaps, PrinterProperties SetAbortProc, StartDoc, StartPage, ResetDC