IPrintOemUI2::DocumentEvent method

The IPrintOemUI2::DocumentEvent method allows a UI plug-in to replace the core driver UI module's default implementation of the DrvDocumentEvent DDI.

Syntax


HRESULT DocumentEvent(
   HANDLE hPrinter,
   HDC    hdc,
   INT    iEsc,
   ULONG  cbIn,
   PVOID  pvIn,
   ULONG  cbOut,
   PVOID  pvOut,
   PINT   piResult
);

Parameters

hPrinter

Caller-supplied printer handle.

hdc

Caller-supplied device context handle, generated by a CreateDC call. This is zero if iEsc is DOCUMENTEVENT_CREATEDCPRE.

iEsc

Caller-supplied escape code identifying the event to be handled. This parameter can be one of the following integer constants:

Escape CodeMeaning

DOCUMENTEVENT_ABORTDOC

GDI is about to process a call to its AbortDoc function.

DOCUMENTEVENT_CREATEDCPOST

GDI has just processed a call to its CreateDC or CreateIC function.

This escape code should not be used unless there has been a previous call to DrvDocumentEvent with iEsc set to DOCUMENTEVENT_CREATEDCPRE.

DOCUMENTEVENT_CREATEDCPRE

GDI is about to process a call to its CreateDC or CreateIC function.

DOCUMENTEVENT_DELETEDC

GDI is about to process a call to its DeleteDC function.

DOCUMENTEVENT_ENDDOCPOST

GDI has just processed a call to its EndDoc function.

DOCUMENTEVENT_ENDDOCPRE

or

DOCUMENTEVENT_ENDDOC

GDI is about to process a call to its EndDoc function.

DOCUMENTEVENT_ENDPAGE

GDI is about to process a call to its EndPage function.

DOCUMENTEVENT_ESCAPE

GDI is about to process a call to its ExtEscape function.

DOCUMENTEVENT_QUERYFILTER

The DOCUMENTEVENT_QUERYFILTER event represents an opportunity for the spooler to query the driver for a list of the DOCUMENTEVENT_XXX events to which the driver will respond. This event is issued just prior to a call to DrvDocumentEvent that passes the DOCUMENTEVENT_CREATEDCPRE event.

DOCUMENTEVENT_RESETDCPOST

GDI has just processed a call to its ResetDC function.

This escape code should not be used unless there has been a previous call to DrvDocumentEvent with iEsc set to DOCUMENTEVENT_RESETDCPRE.

DOCUMENTEVENT_RESETDCPRE

GDI is about to process a call to its ResetDC function.

DOCUMENTEVENT_STARTDOCPOST

GDI has just processed a call to its StartDoc function.

DOCUMENTEVENT_STARTDOCPRE

or

DOCUMENTEVENT_STARTDOC

GDI is about to process a call to its StartDoc function.

DOCUMENTEVENT_STARTPAGE

GDI is about to process a call to its StartPage function.

 

cbIn

Caller-supplied size, in bytes, of the buffer pointed to by pvIn.

pvIn

Caller-supplied pointer, the use of which is dependent on the value supplied for iEsc, as follows:

iEsc ConstantpvIn Contents

DOCUMENTEVENT_ABORTDOC

Not used.

DOCUMENTEVENT_CREATEDCPOST

pvIn contains the address of a pointer to the DEVMODEW structure specified in the pvOut parameter in a previous call to this function, for which the iEsc parameter was set to DOCUMENTEVENT_CREATEDCPRE.

DOCUMENTEVENT_CREATEDCPRE

pvIn points to a DOCEVENT_CREATEDCPRE structure.

DOCUMENTEVENT_DELETEDC

Not used.

DOCUMENTEVENT_ENDDOCPOST

Not used.

DOCUMENTEVENT_ENDDOCPRE

or

DOCUMENTEVENT_ENDDOC

Not used.

DOCUMENTEVENT_ENDPAGE

Not used.

DOCUMENTEVENT_ESCAPE

pvIn points to a DOCEVENT_ESCAPE structure.

DOCUMENTEVENT_QUERYFILTER

Same as for DOCUMENTEVENT_CREATEDCPRE.

DOCUMENTEVENT_RESETDCPOST

pvIn contains the address of a pointer to the DEVMODEW structure specified in the pvOut parameter in a previous call to this function, for which the iEsc parameter was set to DOCUMENTEVENT_RESETDCPRE.

DOCUMENTEVENT_RESETDCPRE

pvIn contains the address of a pointer to a DEVMODEW structure supplied by the caller of ResetDC (described in the Microsoft Windows SDK documentation).

DOCUMENTEVENT_STARTDOCPOST

pvIn points to a LONG that specifies the print job identifier returned by StartDoc (described in the Windows SDK documentation).

DOCUMENTEVENT_STARTDOCPRE

or

DOCUMENTEVENT_STARTDOC

pvIn contains the address of a pointer to a DOCINFO structure supplied by the caller of StartDoc (both described in the Windows SDK documentation).

DOCUMENTEVENT_STARTPAGE

Not used.

 

cbOut

If iEsc is DOCUMENTEVENT_ESCAPE:

Function-supplied value that is used as the cbOutput parameter for ExtEscape.

If iEsc is DOCUMENTEVENT_QUERYFILTER:

Caller-supplied size, in bytes, of the buffer pointer to by pvOut.

For all other iEsc values:

Not used.

pvOut

Function-supplied pointer to an output buffer, the use of which is dependent on the value supplied for iEsc, as follows. CreateDC, ExtEscape, and ResetDC are described in the Windows SDK documentation.

iEsc ConstantpvOut Contents

DOCUMENTEVENT_CREATEDCPRE

Pointer to a driver-supplied DEVMODEW structure, which GDI uses instead of the one supplied by the CreateDC caller. (If NULL, GDI uses the caller-supplied structure.)

DOCUMENTEVENT_ESCAPE

Buffer pointer that is used as the lpszOutData parameter for ExtEscape.

DOCUMENTEVENT_QUERYFILTER

Caller-supplied pointer to buffer containing a DOCEVENT_FILTER structure.

DOCUMENTEVENT_RESETDCPRE

Pointer to a driver-supplied DEVMODEW structure, which GDI uses instead of the one supplied by the ResetDC caller. (If NULL, GDI uses the caller-supplied structure.)

All other iEsc values

Not used.

 

piResult

Pointer to a memory location that receives one of the following values:

Return ValueDefinition

DOCUMENTEVENT_FAILURE

The driver supports the escape code identified by iEsc, but a failure occurred.

DOCUMENTEVENT_SUCCESS

The driver successfully handled the escape code identified by iEsc. Also see the Remarks section for more information.

DOCUMENTEVENT_UNSUPPORTED

The driver does not support the escape code identified by iEsc.

 

Return value

This method should return one of the following values. See the Remarks section for more information.

Return codeDescription
S_OK

The UI plug-in implements this method.

E_NOTIMPL

The UI plug-in does not implement this method.

 

Remarks

A user interface plug-in's IPrintOemUI2::DocumentEvent method performs the same types of operations as the DrvDocumentEvent DDI that is exported by user-mode printer interface DLLs. For information about document events and how they should be processed, see the description of the DrvDocumentEvent DDI.

If you provide a user interface plug-in, the printer driver's DrvDocumentEvent DDI calls the IPrintOemUI2::DocumentEvent method. The DrvDocumentEvent DDI performs its own processing for the specified event, and then calls the IPrintOemUI2::DocumentEvent method to handle additional processing of the event.

When this method is called with a value of the iEsc parameter of DOCUMENTEVENT_QUERYFILTER, and returns with *piResult == DOCUMENTEVENT_SUCCESS, the spooler can interpret this value in either of two ways, depending on whether certain members of the DOCEVENT_FILTER structure changed values. For more information, see the Remarks section for DrvDocumentEvent.

When the DOCUMENTEVENT_QUERYFILTER event is fired, the core driver calls plug-ins in the order they were installed, until one of them returns S_OK, or until all of the plug-ins have been called and none of them returned S_OK. In this way, at most one plug-in is allowed to handle the DOCUMENTEVENT_QUERYFILTER event, and the filter it specifies is applied to all plug-ins in the plug-in chain.

For a plug-in writer who is implementing the IPrintOemUI2 interface, but does not need to support the IPrintOemUI2::DocumentEvent method, this method should return E_NOTIMPL for all values of iEsc. If you do need to implement this method, it should return S_OK for all values of iEsc. This signals the core driver that this method has handled the relevant event. The core driver uses the value that this method places in piResult as the return value for the DrvDocumentEvent DDI.

Requirements

Target platform

Header

Prcomoem.h (include Prcomoem.h)

See also

DrvDocumentEvent
DOCEVENT_FILTER
DOCEVENT_CREATEDCPRE
DOCEVENT_ESCAPE

 

 

Send comments about this topic to Microsoft

Show: