12.6.3 Defining a Function That Cancels a Print Operation

In your application code, you must provide a print-canceling function to process messages for the Abort dialog box. A print-canceling function retrieves messages from the application queue and dispatches them if they are intended for the Abort dialog box. The function continues to loop until it encounters the WM_DESTROY message or until the print operation is complete.

Applications that make lengthy print requests must pass a print-canceling function to GDI to handle special situations during printing operations. The most common situation occurs when a printing operation fills the available disk space before the spooler can copy the data to the printer. Since the spooler can continue to print even though disk space is full, GDI calls the print-canceling function to determine whether it is necessary for the application to cancel the print operation or whether it can simply wait until disk space is free.

To specify the print-canceling function, first retrieve the procedure-instance address for the function:

lpAbortProc = MakeProcInstance((FARPROC) AbortProc, hinst);

Then call the SetAbortProc function, specifying the Abort function's address:

SetAbortProc(hDC, (ABORTPROC) lpAbortProc);

GDI will then call the print-canceling function during spooling. The function must have the following form:

int CALLBACK AbortProc(hdcPrint, Code)
HDC hdcPrint;
int Code;

The hdcPrint parameter identifies the printer device context.

The Code parameter specifies the nature of the call. It can take one of two values:

Once GDI has called the print-canceling function, the function can return TRUE to continue the spooler operation immediately, or FALSE to cancel the printing operation. Most print-canceling functions call the PeekMessage function to temporarily yield control; they then return TRUE to continue the print operation. Yielding control typically gives the spooler enough time to free some disk space.

If the print-canceling function returns FALSE, the printing operation is canceled and the SP_APPABORT error value is returned by the application's next call to the EndPage or EndDoc function.

Important:

If your application encounters a printing error or a canceled print operation, it must not attempt to terminate the operation by using the EndDoc or AbortDoc functions. GDI automatically terminates the operation before returning the error value.

The following example shows the statements required for the print-canceling function:

int CALLBACK AbortProc(hdcPrinter, Code)
HDC hdcPrinter;   /* for multiple printer display contexts */
int Code;         /* for printing status                   */
{
    MSG msg;

/* Process the messages intended for the Abort dialog box. */

    while (PeekMessage((LPMSG) &msg,
           NULL, NULL, NULL, PM_REMOVE))
        if (!IsDialogMessage(hAbortDlgWnd,
                (LPMSG) &msg)) {
            TranslateMessage((LPMSG) &msg);
            DispatchMessage((LPMSG) &msg);
        }

/*
 * The fAbort argument is TRUE (return is FALSE)
 * if the user has canceled the print operation.
 */

    return (!fAbort);
}