Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

                                                     ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
A printer driver provides print job support by handling printer-specific
escapes. GDI passes escapes to a printer driver's Control function whenever
an application calls the Escape function (GDI.38).
 
The QUERYESCSUPPORT Escape
 
All drivers are required to implement the QUERYESCSUPPORT escape. For this
escape, the lpInData parameter points to a 16-bit value that contains the
index of another escape.
 
The driver returns a positive number if the driver implements that escape,
or zero if the escape is unimplemented. The driver always returns nonzero if
the escape queried is QUERYESCSUPPORT.
 
The SETABORTPROC Escape
 
SETABORTPROC is the first escape an application calls when printing. An
application passes a pointer to a callback function in the lpInData
parameter when it calls the SETABORTPROC escape. This callback function is
used to check for user actions such as cancelling the print job. The printer
driver, however, is not responsible for the callback function; GDI modifies
the SETABORTPROC escape so that lpInData points to the application's device
context handle.
 
The hDC parameter given to the driver by this escape should be used with the
OpenJob function to enable the output functions in GDI to call the
application's callback function. Printer drivers generally save this handle
in the PDEVICE structure. If the application does not use SETABORTPROC, NULL
should be passed to the OpenJob function.
 
The STARTDOC Escape
 
Usually, STARTDOC is the escape an application calls. STARTDOC indicates to
GDI and the device driver that the application is printing.
 
This escape also supplies a Print Manager job title in a NULL-terminated
string pointed to by lpInData. The lpOutData parameter is unused. This
supplies the title used by the OpenJob function.
 
Together, with the port name supplied as a parameter to Enable and the hDC
supplied by the SETABORTPROC escape, the driver now has all the data
necessary to call the OpenJob function.
 
RESETDEVICE and STARTDOC Escapes
 
To support the ResetDC and StartDoc functions, which are new to Windows 3.1,
printer drivers must process the RESETDEVICE and STARTDOC escapes in their
Control functions.
 
Although the STARTDOC escape was available in Windows 3.0, the lpInData and
lpOutData parameters have changed. Specifically, lpInData points to a
null-terminated string specifying the name of the document, and lpOutData
points to a DOCINFO structure specifying the output port or file as well as
the document name. The structure has the following form:
 
typedef struct {
    short   cbSize;
    LPSTR   lpszDocName;
    LPSTR   lpszOutput;         // output port name
} DOCINFO, FAR * LPDOCINFO;
 
The lpszOutput is the name of the output file to use. If either lpOutData or
lpszOutput is NULL, the output port given to CreateDC should be used.
 
The RESETDEVICE escape, corresponding to the new ResetDC function, allows
the driver to move a printer's output state from an old physical device
structure to a new one. This allows applications to change the printer
setup, such as orientation, with creating a new print job. For more
information about this escape, see Section 4.1.23, "Other Escapes."
 
The NEWFRAME Escape
 
An application calls the NEWFRAME escape when a new page is to be printed.
The printer driver completes output for the given page and advances to the
next page. NEWFRAME does not use the lpInData or lpOutData parameters.
 
The ENDDOC and ABORTDOC Escapes
 
When an application has completed printing all output, it calls the ENDDOC
escape. ENDDOC does not use either the lpInData or lpOutData parameters. At
this point, the driver may call the CloseJob function.
 
Another common escape is ABORTDOC, which is also called ABORTPIC in older
documentation or applications, and has the same number assigned. This escape
allows GDI or the application to cancel a print job. Generally, if the job
is valid, the driver will clean up and call the DeleteJob function.
 
 
                                      ♦