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

Artikel
03/14/2023

Die IPrintOemUI2::DocumentEvent Methode ermöglicht es einem UI-Plug-In, die Standardimplementierung des DrvDocumentEvent DDI des Haupttreiber-UI-Moduls zu 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 0, 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 seiner AbortDoc-Funktion zu verarbeiten.
DOCUMENTEVENT_CREATEDCPOST	GDI hat gerade einen Aufruf seiner 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 seiner CreateDC - oder CreateIC-Funktion zu verarbeiten.
DOCUMENTEVENT_DELETEDC	GDI ist dabei, einen Aufruf seiner 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 seiner EndPage-Funktion zu verarbeiten.
DOCUMENTEVENT_ESCAPE	GDI ist dabei, einen Aufruf seiner ExtEscape-Funktion zu verarbeiten.
DOCUMENTEVENT_QUERYFILTER	Das DOCUMENTEVENT_QUERYFILTER-Ereignis stellt eine Möglichkeit für den Spooler dar, den Treiber nach einer Liste der DOCUMENTEVENT_XXX-Ereignisse abzufragen, 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, auf den von pvIn verwiesen wird, in Bytes.

pvIn

Vom Aufrufer bereitgestellter Zeiger, dessen Verwendung vom für iEsc angegebenen 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 die 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 (beides wird in der Windows SDK-Dokumentation beschrieben).
DOCUMENTEVENT_STARTPAGE	Wird nicht verwendet.

cbOut

Wenn iEsc DOCUMENTEVENT_ESCAPE ist:

Von der Funktion bereitgestellter Wert, der als cbOutput-Parameter für ExtEscape verwendet wird.

Wenn iEsc DOCUMENTEVENT_QUERYFILTER ist:

Vom Aufrufer bereitgestellte Größe des Pufferzeigers in Bytes auf durch pvOut.

Für alle anderen iEsc-Werte:

Wird nicht verwendet.

pvOut

Von der Funktion bereitgestellter Zeiger auf einen Ausgabepuffer, dessen Verwendung vom für iEsc angegebenen Wert abhängig ist, wie folgt. 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 struktur verwendet. (Bei 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 auf einen Puffer, der eine DOCEVENT_FILTER Struktur enthält.
DOCUMENTEVENT_RESETDCPRE	Zeiger auf eine vom Treiber bereitgestellte DEVMODEW-Struktur, die GDI anstelle der vom ResetDC-Aufrufer bereitgestellten Struktur verwendet. (Bei NULL verwendet GDI die vom Aufrufer bereitgestellte Struktur.)
Alle anderen iEsc-Werte	Wird nicht verwendet.

piResult

Zeiger auf einen Speicherspeicherort, der einen der folgenden Werte empfängt:

Rückgabewert	Definition
DOCUMENTEVENT_FAILURE	Der Treiber unterstützt den von iEsc identifizierten Escapecode, aber es ist ein Fehler aufgetreten.
DOCUMENTEVENT_SUCCESS	Der Treiber hat den von iEsc identifizierten Escapecode erfolgreich verarbeitet. Weitere Informationen finden Sie auch 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.

Hinweise

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

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

Wenn diese Methode mit einem Wert des iEsc-Parameters von DOCUMENTEVENT_QUERYFILTER aufgerufen 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 zu DrvDocumentEvent.

Wenn das DOCUMENTEVENT_QUERYFILTER-Ereignis ausgelöst wird, ruft der Kerntreiber Plug-Ins in der Reihenfolge auf, in der sie installiert wurden, bis eines von ihnen S_OK zurückgibt oder bis alle Plug-Ins aufgerufen wurden und keines von ihnen S_OK zurückgegeben wurde. Auf diese Weise darf höchstens ein Plug-In das DOCUMENTEVENT_QUERYFILTER-Ereignis verarbeiten, und der von diesem Filter festgelegte 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ützen muss, 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. Dies signalisiert dem Kerntreiber, dass diese Methode das relevante Ereignis verarbeitet hat. Der Kerntreiber verwendet den Wert, den diese Methode in piResult als Rückgabewert für drvDocumentEvent DDI platziert.