DocumentEvent-Funktion

Die DocumentEvent-Funktion ist ein Ereignishandler für Ereignisse, die dem Drucken eines Dokuments zugeordnet sind.

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 OpenPrinter- oder AddPrinter-Funktion, um ein Druckerhandle abzurufen.

hdc [ In]

Ein Gerätekontexthandle, das durch einen Aufruf von CreateDCgeneriert wird. Dies ist 0 (null), wenn iEsc auf DOCUMENTEVENT _ CREATEDCPRE festgelegt ist. Einschränkungen beim Drucken aus einer 32-Bit-Anwendung in einer 64-Bit-Version von Windows finden Sie unter Hinweise.

iEsc

Ein Escapecode, der das zu behandelnde Ereignis identifiziert. Dieser Parameter kann eine der folgenden ganzzahligen Konstanten sein.

Konstante Ereignis
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 DocumentEvent 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 der 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 eine Gelegenheit für den Spooler dar, den Treiber nach einer Liste der DOCUMENTEVENT _ XXX-Ereignisse abzufragen, auf die der Treiber antwortet. Dieses Ereignis wird unmittelbar vor einem Aufruf von DocumentEvent ausgegeben, der das DOCUMENTEVENT _ CREATEDCPRE-Ereignis übergibt.
DOCUMENTEVENT _ RESETDCPOST
GDI hat gerade einen Aufruf der ResetDC-Funktion verarbeitet.
Dieser Escapecode sollte nicht verwendet werden, es sei denn, es wurde ein vorheriger Aufruf von DocumentEvent mit iEsc auf DOCUMENTEVENT _ RESETDCPRE festgelegt.
DOCUMENTEVENT _ RESETDCPRE
GDI ist dabei, einen Aufruf der ResetDC-Funktion zu verarbeiten.
DOCUMENTEVENT _ STARTDOCPOST
GDI hat gerade einen Aufruf der 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 seiner StartPage-Funktion zu verarbeiten.

cbIn

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

pvIn [ In]

Ein Zeiger auf einen Puffer. Was der Puffer enthält, 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 Zeigers auf die DEVMODE-Struktur, die im pvOut-Parameter in einem vorherigen Aufruf dieser Funktion angegeben wurde, für die der iEsc-Parameter auf DOCUMENTEVENT _ CREATEDCPRE festgelegt wurde.
DOCUMENTEVENT _ CREATEDCPRE
pvIn verweist auf eine DOCEVENT _ CREATEDCPRE-Struktur, die im Windows Driver Development Kitdokumentiert 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 Driver Development Kitdokumentiert ist.
DOCUMENTEVENT _ QUERYFILTER
Identisch mit DOCUMENTEVENT _ CREATEDCPRE.
DOCUMENTEVENT _ RESETDCPOST
pvIn enthält die Adresse eines Zeigers auf die DEVMODE-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 die DEVMODE-Struktur, die vom Aufrufer von ResetDCbereitgestellt wird.
DOCUMENTEVENT _ STARTDOCPOST
pvIn zeigt auf einen LONG-Wert, der den von StartDoczurückgegebenen Druckauftragsbezeichner angibt.
DOCUMENTEVENT _ STARTDOCPRE oder DOCUMENTEVENT _ STARTDOC
pvIn enthält die Adresse eines Zeigers auf eine DOCINFO-Struktur, die vom Aufrufer von StartDocbereitgestellt wird.
DOCUMENTEVENT _ STARTPAGE
Wird nicht verwendet.
*cbOut*
Wert Bedeutung
IDOCUMENTEVENT _ QUERYFILTER Die Größe des Pufferzeigers auf durch pvOut in Bytes.
DOCUMENTEVENT _ ESCAPE Ein -Wert, der als cbOutput-Parameter für ExtEscapeverwendet wird.
Für alle anderen Werte iEsc wird nicht verwendet.

pvOut [ out]

Ein Zeiger auf einen Puffer. Der Inhalt des Puffers hängt vom für iEsc angegebenen Wert ab, wie in der folgenden Tabelle dargestellt.

Konstante pvOut-Inhalt
DOCUMENTEVENT _ CREATEDCPRE
Ein Zeiger auf eine vom Treiber bereitgestellte DEVMODE-Struktur, die von GDI anstelle der vom CreateDC-Aufrufer bereitgestellten Verwendet wird. (Bei NULL verwendet GDI die vom Aufrufer bereitgestellte -Struktur.)
DOCUMENTEVENT _ ESCAPE
Ein Zeiger auf einen Puffer, der als lpszOutData-Parameter für ExtEscape verwendet wird.
DOCUMENTEVENT _ QUERYFILTER
Ein Zeiger auf den Puffer, der eine DOCEVENT FILTER-Struktur enthält, die im Windows _ Driver Development Kit dokumentiert ist.
DOCUMENTEVENT _ RESETDCPRE
Ein Zeiger auf eine vom Treiber bereitgestellte DEVMODE-Struktur, die von GDI anstelle der vom ResetDC-Aufrufer bereitgestellten verwendet wird. (Bei NULL verwendet GDI die vom Aufrufer bereitgestellte -Struktur.)

Rückgabewert

Der Rückgabewert der Funktion hängt von dem für iEsc bereitgestellten Escape-Wert ab. Bei einigen Escapecodes wird der Rückgabewert nicht verwendet (siehe unten). Wenn die Funktion einen Rückgabewert liefert, muss es einer der folgenden sein.

Rückgabewert Bedeutung
_DOCUMENTEVENT-FEHLER 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.
DOCUMENTEVENT _ NICHT UNTERSTÜTZT Der Treiber unterstützt den von iEsc identifizierten Escapecode nicht.

Die folgende Liste gibt an, welche Escapecodes einen Rückgabewert erfordern und welche nicht, und erläutert die Bedeutung der Rückgabecodes DOCUMENTEVENT _ SUCCESS, DOCUMENTEVENT FAILURE und _ DOCUMENTEVENT _ UNSUPPORTED.

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: GDI erstellt weder den Gerätekontext noch den Informationskontext und stellt den Rückgabewert 0 für _ CreateDC oder CreateIC zur Verfügung.
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: GDI setzt den Gerätekontext nicht zurück und gibt den Rückgabewert 0 für _ ResetDC an.
DOCUMENTEVENT _ STARTDOCPOST DOCUMENTEVENT _ FAILURE : GDI ruft AbortDoc auf, um das Dokument zu beenden, und gibt dann den Rückgabewert SP _ ERROR für StartDoc an.
DOCUMENTEVENT _ STARTDOCPRE oder DOCUMENTEVENT _ STARTDOC DOCUMENTEVENT FAILURE : GDI startet das Dokument nicht und gibt den Rückgabewert _ SP _ ERROR für StartDoc an.
DOCUMENTEVENT _ STARTPAGE DOCUMENTEVENT FAILURE : GDI startet die Seite nicht und gibt den Rückgabewert _ SP _ ERROR für StartPage an.

Bemerkungen

Bei einem iEsc-Wert von DOCUMENTEVENT QUERYFILTER kann der Spooler einen von DocumentEvent zurückgegebenen DOCUMENTEVENT SUCCESS-Wert auf zwei Arten interpretieren, je nachdem, ob der Treiber bestimmte Elemente der DOCEVENT FILTER-Struktur geändert hat (dies ist im _ Windows Driver Development Kit _ _ dokumentiert). (Der pvOut-Parameter verweist auf diese Struktur.) Wenn der Spooler Speicher für eine Struktur dieses Typs zuteilen, initialisiert er zwei Member dieser Struktur, cElementsReturned und cElementsNeeded, für bekannte Werte. Nachdem DocumentEvent zurückgegeben wurde, bestimmt der Spooler, ob sich die Werte dieser Member geändert haben, und verwendet diese Informationen, um den DocumentEvent-Rückgabewert zu interpretieren. In der folgenden Tabelle wird diese Situation zusammengefasst.

Rückgabewert Status von cElementsReturned und cElementsNeeded Bedeutung
DOCUMENTEVENT _ SUCCESS
Der Treiber hat keine Änderung an beiden Membern vorgenommen.
Der Spooler interpretiert diesen Rückgabewert als äquivalent zu DOCUMENTEVENT _ UNSUPPORTED. Der Spooler kann den Ereignisfilter nicht vom Treiber abrufen, sodass er beim Aufrufen von DocumentEvent für alle Ereignisse beibehalten wird.
DOCUMENTEVENT _ SUCCESS
Der Treiber hat in einen oder beide Member geschrieben.
Der Spooler akzeptiert diesen Rückgabewert ohne Interpretation. Wenn der Treiber nur in eines von cElementsNeeded und cElementsReturned geschrieben hat, betrachtet der Spooler das unveränderte Element als wert 0 (null).
Der Spooler filtert alle Ereignisse heraus, die im aDocEventCall-Mitglied von DOCEVENT FILTER aufgeführt sind (dies ist im Windows _ Driver Development Kit dokumentiert).
DOCUMENTEVENT _ NICHT UNTERSTÜTZT
Nicht zutreffend
Der Treiber unterstützt DOCUMENTEVENT _ QUERYFILTER nicht.
Der Spooler kann den Ereignisfilter nicht vom Treiber abrufen, sodass er beim Aufrufen von DocumentEvent für alle Ereignisse beibehalten wird.
_DOCUMENTEVENT-FEHLER
Nicht zutreffend
Der Treiber unterstützt DOCUMENTEVENT _ QUERYFILTER, aber es ist ein interner Fehler aufgetreten.
Der Spooler kann den Ereignisfilter nicht vom Treiber abrufen, sodass er beim Aufrufen von DocumentEvent für alle Ereignisse beibehalten wird.

Wenn der im iEsc-Parameter angegebene Escapecode DOCUMENTEVENT _ CREATEDCPRE ist, 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 zu DOCEVENT. _ CREATEDCPRE-Struktur im Windows Driver Development Kit.)
  • Wenn der Auftrag in einen Pool poolt wird, zeigt pvIn->pszDevice auf den Druckerportnamen.

Hinweis

Die folgenden Einschränkungen gelten beim Ausführen einer 32-Bit-Anwendung auf einer 64-Bit-Version Windows. Die einzige GDI-Funktion, die DocumentEvent aufrufen sollte, ist ExtEscape,und es sollten nur private Escapes verwendet werden. DocumentEvent-Aufrufe anderer GDI-Funktionen können zu nicht definiertem Verhalten führen.

Requirements (Anforderungen)

Anforderung Wert
Unterstützte Mindestversion (Client)
Windows Nur [ Vista-Desktop-Apps]
Unterstützte Mindestversion (Server)
Windows Nur Server [ 2008-Desktop-Apps]
Header
Winspool.h (include Windows.h)
Unicode- und ANSI-Name
DocumentEventW (Unicode) und DocumentEventA (ANSI)

Weitere Informationen

Drucken

Druckspooler-API-Funktionen

Windows Driver Development Kit