IPrintOemUI2::D ocumentEvent-Methode (prcomoem.h)

Artikel
02/07/2025

Mit der IPrintOemUI2::DocumentEvent-Methode kann ein UI-Plug-In die Standardimplementierung des DrvDocumentEvent DDI ersetzen.

Syntax

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

Parameter

hPrinter

Vom Anrufer bereitgestellter Druckerhandle.

hdc

Vom Aufrufer bereitgestelltes Gerätekontexthandle, das von einem CreateDC Aufruf generiert wird. Dies ist null, wenn iEsc- DOCUMENTEVENT_CREATEDCPRE ist.

iEsc

Vom Aufrufer bereitgestellter Escapecode, der das zu behandelnde Ereignis identifiziert. Dieser Parameter kann eine der folgenden ganzzahligen Konstanten sein:

Escapecode	Bedeutung
DOCUMENTEVENT_ABORTDOC	GDI ist dabei, einen Aufruf der AbortDoc--Funktion zu verarbeiten.
DOCUMENTEVENT_CREATEDCPOST	GDI hat gerade einen Aufruf der CreateDC- oder CreateIC--Funktion verarbeitet. Dieser Escapecode sollte nur verwendet werden, wenn ein vorheriger Aufruf von DrvDocumentEvent mit iEsc- auf DOCUMENTEVENT_CREATEDCPRE festgelegt wurde.
DOCUMENTEVENT_CREATEDCPRE	GDI ist dabei, einen Aufruf der CreateDC- oder CreateIC--Funktion zu verarbeiten.
DOCUMENTEVENT_DELETEDC	GDI ist dabei, einen Aufruf der DeleteDC--Funktion zu verarbeiten.
DOCUMENTEVENT_ENDDOCPOST	GDI hat gerade einen Aufruf seiner EndDoc--Funktion verarbeitet.
DOCUMENTEVENT_ENDDOCPRE oder DOCUMENTEVENT_ENDDOC	GDI ist dabei, einen Aufruf seiner EndDoc--Funktion zu verarbeiten.
DOCUMENTEVENT_ENDPAGE	GDI ist dabei, einen Aufruf der EndPage--Funktion zu verarbeiten.
DOCUMENTEVENT_ESCAPE	GDI ist dabei, einen Aufruf der ExtEscape--Funktion zu verarbeiten.
DOCUMENTEVENT_QUERYFILTER	Das DOCUMENTEVENT_QUERYFILTER-Ereignis stellt die Möglichkeit dar, dass der Spooler den Treiber nach einer Liste der DOCUMENTEVENT_XXX--Ereignisse abfragt, auf die der Treiber antwortet. Dieses Ereignis wird direkt vor einem Aufruf von DrvDocumentEvent ausgegeben, der das DOCUMENTEVENT_CREATEDCPRE-Ereignis übergibt.
DOCUMENTEVENT_RESETDCPOST	GDI hat gerade einen Aufruf seiner ResetDC--Funktion verarbeitet. Dieser Escapecode sollte nur verwendet werden, wenn ein vorheriger Aufruf von DrvDocumentEvent mit iEsc- auf DOCUMENTEVENT_RESETDCPRE festgelegt wurde.
DOCUMENTEVENT_RESETDCPRE	GDI ist dabei, einen Aufruf der ResetDC-Funktion zu verarbeiten.
DOCUMENTEVENT_STARTDOCPOST	GDI hat gerade einen Aufruf seiner StartDoc--Funktion verarbeitet.
DOCUMENTEVENT_STARTDOCPRE oder DOCUMENTEVENT_STARTDOC	GDI ist dabei, einen Aufruf der StartDoc--Funktion zu verarbeiten.
DOCUMENTEVENT_STARTPAGE	GDI ist dabei, einen Aufruf der StartPage--Funktion zu verarbeiten.

cbIn

Vom Aufrufer bereitgestellte Größe des Puffers in Byte, auf den pvInverweist.

pvIn

Vom Aufrufer bereitgestellter Zeiger, deren Verwendung von dem für iEscangegebenen Wert abhängig ist, wie folgt:

iEsc- Konstante	pvIn Inhalt
DOCUMENTEVENT_ABORTDOC	Wird nicht verwendet.
DOCUMENTEVENT_CREATEDCPOST	pvIn- enthält die Adresse eines Zeigers auf die DEVMODEW- Struktur, die im pvOut- Parameter in einem vorherigen Aufruf dieser Funktion angegeben wurde, für den der iEsc Parameter auf DOCUMENTEVENT_CREATEDCPRE festgelegt wurde.
DOCUMENTEVENT_CREATEDCPRE	pvIn verweist auf eine DOCEVENT_CREATEDCPRE Struktur.
DOCUMENTEVENT_DELETEDC	Wird nicht verwendet.
DOCUMENTEVENT_ENDDOCPOST	Wird nicht verwendet.
DOCUMENTEVENT_ENDDOCPRE oder DOCUMENTEVENT_ENDDOC	Wird nicht verwendet.
DOCUMENTEVENT_ENDPAGE	Wird nicht verwendet.
DOCUMENTEVENT_ESCAPE	pvIn verweist auf eine DOCEVENT_ESCAPE Struktur.
DOCUMENTEVENT_QUERYFILTER	Identisch mit DOCUMENTEVENT_CREATEDCPRE.
DOCUMENTEVENT_RESETDCPOST	pvIn- enthält die Adresse eines Zeigers auf die DEVMODEW- Struktur, die im pvOut Parameter in einem vorherigen Aufruf dieser Funktion angegeben wurde, für den der iEsc Parameter auf DOCUMENTEVENT_RESETDCPRE festgelegt wurde.
DOCUMENTEVENT_RESETDCPRE	pvIn- enthält die Adresse eines Zeigers auf eine DEVMODEW- Struktur, die vom Aufrufer von ResetDC bereitgestellt wird (in der Microsoft Windows SDK-Dokumentation beschrieben).
DOCUMENTEVENT_STARTDOCPOST	pvIn- verweist auf einen LONG-Wert, der den von StartDoc- zurückgegebenen Druckauftragsbezeichner angibt (in der Windows SDK-Dokumentation beschrieben).
DOCUMENTEVENT_STARTDOCPRE oder DOCUMENTEVENT_STARTDOC	pvIn- enthält die Adresse eines Zeigers auf eine DOCINFO-Struktur, die vom Aufrufer von StartDoc- bereitgestellt wird (beide in der Windows SDK-Dokumentation beschrieben).
DOCUMENTEVENT_STARTPAGE	Wird nicht verwendet.

cbOut

Wenn iEsc DOCUMENTEVENT_ESCAPE ist:

Funktionslieferwert, der als cbOutput Parameter für ExtEscape-verwendet wird.

Wenn iEsc DOCUMENTEVENT_QUERYFILTER ist:

Vom Aufrufer bereitgestellte Größe des Pufferzeigers in Bytes bis pvOut-.

Für alle anderen iEsc-Werte:

Wird nicht verwendet.

pvOut

Der von der Funktion bereitgestellte Zeiger auf einen Ausgabepuffer hängt von dem für iEscangegebenen Wert ab. CreateDC-, ExtEscape-und ResetDC- werden in der Windows SDK-Dokumentation beschrieben.

iEsc- Konstante	pvOut Inhalt
DOCUMENTEVENT_CREATEDCPRE	Zeiger auf eine vom Treiber bereitgestellte DEVMODEW-Struktur, die GDI anstelle der vom CreateDC Aufrufer bereitgestellten verwendet. (Wenn NULL-verwendet GDI die vom Aufrufer bereitgestellte Struktur.)
DOCUMENTEVENT_ESCAPE	Pufferzeiger, der als lpszOutData Parameter für ExtEscape-verwendet wird.
DOCUMENTEVENT_QUERYFILTER	Vom Aufrufer bereitgestellter Zeiger zum Puffer, der eine DOCEVENT_FILTER Struktur enthält.
DOCUMENTEVENT_RESETDCPRE	Zeiger auf eine vom Treiber bereitgestellte DEVMODEW-Struktur, die GDI anstelle des vom ResetDC Aufrufer bereitgestellten verwendet. (Wenn NULL-verwendet GDI die vom Aufrufer bereitgestellte Struktur.)
Alle anderen iEsc- Werte	Wird nicht verwendet.

piResult

Zeigen Sie auf einen Speicherspeicherort, der einen der folgenden Werte empfängt:

Rückgabewert	Definition
DOCUMENTEVENT_FAILURE	Der Treiber unterstützt den von iEscidentifizierten Escapecode, aber ein Fehler ist aufgetreten.
DOCUMENTEVENT_SUCCESS	Der Treiber hat den von iEscidentifizierten Escapecode erfolgreich verarbeitet. Weitere Informationen finden Sie im Abschnitt "Hinweise".
DOCUMENTEVENT_UNSUPPORTED	Der Treiber unterstützt den von iEsc-identifizierten Escapecode nicht.

Rückgabewert

Diese Methode sollte einen der folgenden Werte zurückgeben. Weitere Informationen finden Sie im Abschnitt "Hinweise".

Rückgabecode	Beschreibung
S_OK	Das UI-Plug-In implementiert diese Methode.
E_NOTIMPL	Das UI-Plug-In implementiert diese Methode nicht.

Bemerkungen

Die IPrintOemUI2::DocumentEvent-Methode eines Plug-Ins für die Benutzeroberfläche führt dieselben Arten von Vorgängen wie die DrvDocumentEvent DDI aus, die von DLLs der Druckerschnittstelle des Benutzermodus exportiert wird. Informationen zu Dokumentereignissen und deren Verarbeitung finden Sie in der Beschreibung des DrvDocumentEvent DDI.

Wenn Sie ein Plug-In für die Benutzeroberfläche bereitstellen, ruft der DrvDocumentEvent DDI des Druckertreibers die IPrintOemUI2::DocumentEvent-Methode auf. Das DrvDocumentEvent DDI führt eine eigene Verarbeitung für das angegebene Ereignis durch und ruft dann die IPrintOemUI2::DocumentEvent Methode auf, um zusätzliche Verarbeitung des Ereignisses zu verarbeiten.

Wenn diese Methode mit einem Wert des iEsc- Parameters von DOCUMENTEVENT_QUERYFILTER aufgerufen wird und mit *piResult == DOCUMENTEVENT_SUCCESS zurückgegeben wird, kann der Spooler diesen Wert auf zwei Arten interpretieren, je nachdem, ob bestimmte Member der DOCEVENT_FILTER Struktur Werte geändert haben. Weitere Informationen finden Sie im Abschnitt "Hinweise" für DrvDocumentEvent.

Wenn das DOCUMENTEVENT_QUERYFILTER-Ereignis ausgelöst wird, ruft der Kerntreiber Plug-Ins in der Reihenfolge auf, in der sie installiert wurden, bis einer von ihnen S_OK zurückgibt, oder bis alle Plug-Ins aufgerufen wurden und keine von ihnen S_OK zurückgegeben wurde. Auf diese Weise ist es höchstens einem Plug-In gestattet, das DOCUMENTEVENT_QUERYFILTER-Ereignis zu verarbeiten, und der angegebene Filter wird auf alle Plug-Ins in der Plug-In-Kette angewendet.

Für einen Plug-In-Writer, der die IPrintOemUI2 Schnittstelle implementiert, die IPrintOemUI2::DocumentEvent-Methode jedoch nicht unterstützt, sollte diese Methode E_NOTIMPL für alle Werte von iEsc-zurückgeben. Wenn Sie diese Methode implementieren müssen, sollte sie S_OK für alle Werte von iEsc-zurückgeben. Dadurch wird der Kerntreiber signalisiert, dass diese Methode das relevante Ereignis behandelt hat. Der Kerntreiber verwendet den Wert, den diese Methode in piResult als Rückgabewert für die DrvDocumentEvent DDI platziert.