Share via

DocumentEvent-Funktion

  • Artikel

Die DocumentEvent-Funktion ist ein Ereignishandler für Ereignisse im Zusammenhang mit dem Drucken eines Dokuments.

Syntax

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

Parameter

hPrinter [in]

Ein Handle für ein Druckerobjekt. Verwenden Sie die Funktionen OpenPrinter oder AddPrinter, um ein Druckerhandle abzurufen.

hdc [in]

Ein Gerätekontexthandle, das durch einen Aufruf von CreateDC generiert wird. Es ist null, wenn iEsc auf DOCUMENTEVENT_CREATEDCPRE festgelegt ist. Einschränkungen beim Drucken mit einer 32-Bit-Anwendung in einer 64-Bit-Version von Windows finden Sie in den Hinweisen.

iEsc

Ein Escapecode, der das Ereignis identifiziert, das bearbeitet werden soll. Dieser Parameter kann eine der folgenden Integerkonstanten sein.

Konstante Ereignis
DOCUMENTEVENT_ABORTDOC
 Das GDI soll einen Aufruf seiner AbortDoc-Funktion verarbeiten.
DOCUMENTEVENT_CREATEDCPOST
 Das GDI hat einen Aufruf der Funktionen CreateDC oder CreateIC verarbeitet.
Dieser Escapecode sollte lediglich dann verwendet werden, wenn ein vorheriger Aufruf von DocumentEvent mit iEsc auf DOCUMENTEVENT_CREATEDCPRE festgelegt wurde.
DOCUMENTEVENT_CREATEDCPRE
 Das GDI soll einen Aufruf seiner Funktionen CreateDC oder CreateIC verarbeiten.
DOCUMENTEVENT_DELETEDC
 Das GDI soll einen Aufruf seiner DeleteDC-Funktion verarbeiten.
DOCUMENTEVENT_ENDDOCPOST
 Das GDI hat einen Aufruf seiner EndDoc-Funktion verarbeitet.
DOCUMENTEVENT_ENDDOCPRE oder DOCUMENTEVENT_ENDDOC
 Das GDI soll einen Aufruf seiner EndDoc-Funktion verarbeiten.
DOCUMENTEVENT_ENDPAGE
 Das GDI soll einen Aufruf seiner EndPage-Funktion verarbeiten.
DOCUMENTEVENT_ESCAPE
 Das GDI soll einen Aufruf seiner ExtEscape-Funktion verarbeiten.
DOCUMENTEVENT_QUERYFILTER
 Das DOCUMENTEVENT_QUERYFILTER-Ereignis stellt eine Möglichkeit dar, mit der der Spooler den Treiber nach einer Liste der DOCUMENTEVENT_ XXX-Ereignisse abfragen kann, auf die der Treiber antwortet. Dieses Ereignis wird vor einem Aufruf der DocumentEvent-Funktion ausgegeben, die das Ereignis DOCUMENTEVENT_CREATEDCPRE übergibt.
DOCUMENTEVENT_RESETDCPOST
 Das GDI hat einen Aufruf seiner ResetDC-Funktion verarbeitet.
Dieser Escapecode sollte lediglich dann verwendet werden, wenn ein vorheriger Aufruf der DocumentEvent-Funktion mit iEsc auf DOCUMENTEVENT_RESETDCPRE festgelegt wurde.
DOCUMENTEVENT_RESETDCPRE
 Das GDI soll einen Aufruf seiner ResetDC-Funktion verarbeiten.
DOCUMENTEVENT_STARTDOCPOST
 Das GDI hat einen Aufruf seiner StartDoc-Funktion verarbeitet.
DOCUMENTEVENT_STARTDOCPRE oder DOCUMENTEVENT_STARTDOC
 Das GDI soll einen Aufruf seiner StartDoc-Funktion verarbeiten.
DOCUMENTEVENT_STARTPAGE
 Das GDI soll einen Aufruf seiner StartPage-Funktion verarbeiten.

cbIn

Die Größe des Puffers in Bytes, auf den pvIn verweist

pvIn [in]

Ein Verweis auf einen Puffer. Der Inhalt des Puffers hängt vom Wert von iEsc ab, wie in der folgenden Tabelle dargestellt.

Konstante Pvin-Inhalt
DOCUMENTEVENT_ABORTDOC
 Wird nicht verwendet.
DOCUMENTEVENT_CREATEDCPOST
 pvIn enthält die Adresse eines Verweises auf die DEVMODE-Struktur, die in einem vorherigen Aufruf dieser Funktion im pvOut-Parameter angegeben wurde. Hierfür wurde der iEsc-Parameter auf DOCUMENTEVENT_CREATEDCPRE festgelegt.
DOCUMENTEVENT_CREATEDCPRE
 pvIn verweist auf eine DOCEVENT_CREATEDCPRE-Struktur, die im Windows-Treiberentwicklungskit dokumentiert ist.
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, die im Windows-Treiberentwicklungskit dokumentiert ist.
DOCUMENTEVENT_QUERYFILTER
 Wie bei DOCUMENTEVENT_CREATEDCPRE
DOCUMENTEVENT_RESETDCPOST
 pvIn enthält die Adresse eines Verweises auf die DEVMODE-Struktur, die im pvOut-Parameter in einem vorherigen Aufruf dieser Funktion angegeben wurde. Hierfür wurde der iEsc-Parameter auf DOCUMENTEVENT_RESETDCPRE festgelegt.
DOCUMENTEVENT_RESETDCPRE
 pvIn enthält die Adresse eines Verweises auf die DEVMODE-Struktur, die vom Aufrufer von ResetDC bereitgestellt wird.
DOCUMENTEVENT_STARTDOCPOST
 pvIn verweist auf einen LONG-Wert, der den von StartDoc zurückgegebenen Druckauftragsbezeichner angibt.
DOCUMENTEVENT_STARTDOCPRE oder DOCUMENTEVENT_STARTDOC
 pvIn enthält die Adresse eines Verweises auf die DOCINFO-Struktur, die vom Aufrufer von StartDoc bereitgestellt wird.
DOCUMENTEVENT_STARTPAGE
 Wird nicht verwendet.

cbOut

Wert Bedeutung
IDOCUMENTEVENT_QUERYFILTER Die Größe des Puffers in Bytes, auf den pvOut verweist.
DOCUMENTEVENT_ESCAPE Ein Wert, der als cbOutput-Parameter für ExtEscape verwendet wird.
Alle anderen Werte iEsc wird nicht verwendet.

pvOut [out]

Ein Verweis auf einen Puffer. Der Inhalt des Puffers hängt von dem für iEsc bereitgestellten Wert ab, wie in der folgenden Tabelle dargestellt.

Konstante pvOut-Inhalt
DOCUMENTEVENT_CREATEDCPRE
 Ein Verweis auf eine vom Treiber bereitgestellte DEVMODE-Struktur, die das GDI anstelle des vom CreateDC-Aufrufer bereitgestellten Verweises verwendet. (Bei NULL verwendet das GDI die vom Aufrufer bereitgestellte Struktur.)
DOCUMENTEVENT_ESCAPE
 Ein Verweis auf einen Puffer, der als lpszOutData-Parameter für ExtEscape verwendet wird.
DOCUMENTEVENT_QUERYFILTER
 Ein Verweis, der eine DOCEVENT_FILTER-Struktur enthält, die im Windows-Treiberentwicklungskit dokumentiert ist.
DOCUMENTEVENT_RESETDCPRE
 Ein Verweis auf eine vom Treiber bereitgestellte DEVMODE-Struktur, die das GDI anstelle des vom ResetDC-Aufrufer bereitgestellten Verweises verwendet. (Bei NULL verwendet das GDI die vom Aufrufer bereitgestellte Struktur.)

Rückgabewert

Der Rückgabewert der Funktion ist von dem für iEsc angegebenen Escapewert abhängig. Für einige Escapecodes wird der Rückgabewert nicht verwendet (siehe unten). Der durch eine Funktion bereitgestellte Rückgabewert muss einem der folgenden entsprechen.

Rückgabewert Bedeutung
DOCUMENTEVENT_FAILURE Der Treiber unterstützt den von iEsc identifizierten Escapecode, allerdings ist ein Fehler aufgetreten.
DOCUMENTEVENT_SUCCESS Der Treiber hat den von iEsc identifizierten Escapecode erfolgreich verarbeitet.
DOCUMENTEVENT_UNSUPPORTED Der Treiber unterstützt den von iEsc identifizierten Escapecode nicht.

In der folgenden Liste wird angegeben, welche Escapecodes einen Rückgabewert erfordern. Außerdem wird erläutert, was die Rückgabecodes DOCUMENTEVENT_SUCCESS, DOCUMENTEVENT_FAILURE und DOCUMENTEVENT_UNSUPPORTED bedeuten.

Rückgabewert Bedeutung
DOCUMENTEVENT_ABORTDOC Der Rückgabewert wird nicht verwendet und sollte nicht gelesen werden.
DOCUMENTEVENT_CREATEDCPOST Der Rückgabewert wird nicht verwendet und sollte nicht gelesen werden.
DOCUMENTEVENT_CREATEDCPRE DOCUMENTEVENT_FAILURE – das GDI erstellt keinen Geräte- oder Informationskontext und stellt einen Rückgabewert von 0 für CreateDC oder CreateIC bereit.
DOCUMENTEVENT_DELETEDC Der Rückgabewert wird nicht verwendet und sollte nicht gelesen werden.
DOCUMENTEVENT_ENDDOCPOST Der Rückgabewert wird nicht verwendet und sollte nicht gelesen werden.
DOCUMENTEVENT_ENDDOCPRE oder DOCUMENTEVENT_ENDDOC Der Rückgabewert wird nicht verwendet und sollte nicht gelesen werden.
DOCUMENTEVENT_ENDPAGE Der Rückgabewert wird nicht verwendet und sollte nicht gelesen werden.
DOCUMENTEVENT_ESCAPE Der Rückgabewert wird nicht verwendet und sollte nicht gelesen werden.
DOCUMENTEVENT_QUERYFILTER Siehe Hinweise.
DOCUMENTEVENT_RESETDCPOST Der Rückgabewert wird nicht verwendet und sollte nicht gelesen werden.
DOCUMENTEVENT_RESETDCPRE DOCUMENTEVENT_FAILURE – das GDI setzt den Gerätekontext nicht zurück und stellt einen Rückgabewert von 0 für ResetDC bereit.
DOCUMENTEVENT_STARTDOCPOST DOCUMENTEVENT_FAILURE – das GDI ruft AbortDoc auf, um das Dokument zu beenden, und stellt anschließend einen Rückgabewert von SP_ERROR für StartDoc bereit.
DOCUMENTEVENT_STARTDOCPRE oder DOCUMENTEVENT_STARTDOC DOCUMENTEVENT_FAILURE – das GDI startet das Dokument nicht und stellt einen Rückgabewert von SP_ERROR für StartDoc bereit.
DOCUMENTEVENT_STARTPAGE DOCUMENTEVENT_FAILURE – das GDI startet die Seite nicht und stellt einen Rückgabewert von SP_ERROR für StartPage bereit.

Hinweise

Bei einem iEsc-Wert von DOCUMENTEVENT_QUERYFILTER kann der Spooler einen von DocumentEvent zurückgegebenen DOCUMENTEVENT_SUCCESS-Wert auf zwei Arten interpretieren. Die Art der Interpretation hängt davon ab, ob der Treiber bestimmte Member der DOCEVENT_FILTER-Struktur geändert hat, was im Windows-Treiberentwicklungskit dokumentiert ist. (Der pvOut-Parameter verweist auf diese Struktur.) Wenn der Spooler für eine Struktur dieses Typs Arbeitsspeicher zuweist, initialisiert er für bekannte Werte die beiden Member cElementsReturned und cElementsNeededed dieser Struktur. Nachdem DocumentEvent zurückgegeben wurde, bestimmt der Spooler, ob sich die Werte dieser Member geändert haben. Diese Informationen werden vom Spooler verwendet, um den DocumentEvent-Rückgabewert zu interpretieren. Die folgende Tabelle enthält eine Zusammenfassung dieser Situation.

Rückgabewert Status von cElementsReturned und cElementsNeeded Bedeutung
DOCUMENTEVENT_SUCCESS
 Der Treiber hat an beiden Membern keine Änderung vorgenommen.
 Der Spooler interpretiert diesen Rückgabewert als gleichwertig zu DOCUMENTEVENT_UNSUPPORTED. Der Spooler kann den Ereignisfilter nicht über den Treiber abrufen, sodass er weiterhin DocumentEvent für alle Ereignisse aufruft.
DOCUMENTEVENT_SUCCESS
 Der Treiber hat in einen oder beide Member geschrieben.
 Der Spooler akzeptiert diesen Rückgabewert ohne Interpretation. Wenn der Treiber lediglich in einen Member von cElementsNeededed und cElementsReturned geschrieben hat, betrachtet der Spooler das unveränderte Element als einen Wert von null.
Der Spooler filtert alle Ereignisse aus, die im aDocEventCall-Member von DOCEVENT_FILTER aufgeführt sind. Das ist im Windows-Treiberentwicklungskit dokumentiert.
DOCUMENTEVENT_UNSUPPORTED
 Nicht zutreffend
 Der Treiber unterstützt DOCUMENTEVENT_QUERYFILTER nicht.
Der Spooler kann den Ereignisfilter nicht über den Treiber abrufen, sodass er weiterhin DocumentEvent für alle Ereignisse aufruft.
DOCUMENTEVENT_FAILURE
 Nicht zutreffend
 Der Treiber unterstützt DOCUMENTEVENT_QUERYFILTER, allerdings ist ein interner Fehler aufgetreten.
Der Spooler kann den Ereignisfilter nicht über den Treiber abrufen, sodass er weiterhin DocumentEvent für alle Ereignisse aufruft.

Wenn es sich beim im iEsc-Parameter bereitgestellten Escapecode um DOCUMENTEVENT_CREATEDCPRE handelt, gelten die folgenden Regeln:

  • Wenn der Auftrag ohne Spooling direkt an den Drucker gesendet wird, verweist pvIn>pszDevice auf den Druckernamen. (Weitere Informationen finden Sie in der Dokumentation zur DOCEVENT_CREATEDCPRE-Struktur im Windows-Treiberentwicklungskit.)
  • Wenn der Auftrag gespoolt wird, verweist pvIn>pszDevice auf den Namen des Druckerports.

Hinweis

Die folgenden Einschränkungen gelten beim Ausführen einer 32-Bit-Anwendung in einer 64-Bit-Version von Windows. ExtEscape ist die einzige GDI-Funktion, die DocumentEvent aufrufen soll, und es sollten ausschließlich private Escapes verwendet werden. DocumentEvent-Aufrufe für andere GDI-Funktionen können zu nicht definiertem Verhalten führen.

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client)
 Windows Vista [nur Desktop-Apps]
Minimal unterstützter Server
 Windows Server 2008 [nur Desktop-Apps]
Header
Winspool.h (einschließlich „Windows.h“)
Unicode- und ANSI-Namen
 DocumentEventW (Unicode) und DocumentEventA (ANSI)

Siehe auch