DrvDocumentEvent-Funktion (winddiui.h)

  • Artikel

Die DrvDocumentEvent-Funktion einer Druckerschnittstellen-DLL kann bestimmte Ereignisse behandeln, die mit dem Drucken eines Dokuments verbunden sind.

Syntax

int DrvDocumentEvent(
        HANDLE hPrinter,
        HDC    hdc,
        int    iEsc,
        ULONG  cbIn,
  [in]  PVOID  pvIn,
        ULONG  cbOut,
  [out] PVOID  pvOut
);

Parameter

hPrinter

Vom Anrufer bereitgestellter Druckerhandle.

hdc

Vom Aufrufer bereitgestelltes Gerätekontexthandle, das von einem CreateDC generiert wird. Dies ist null, wenn iEsc auf DOCUMENTEVENT_CREATEDCPRE festgelegt ist. Einschränkungen beim Drucken aus einer 32-Bit-Anwendung unter einer 64-Bit-Version von Windows finden Sie weiter unten im Abschnitt Hinweise .

iEsc

Vom Aufrufer bereitgestellter Escapecode, der das zu behandelnde Ereignis identifiziert.

Einschränkungen beim Drucken aus einer 32-Bit-Anwendung unter einer 64-Bit-Version von Windows finden Sie weiter unten im Abschnitt Hinweise .

Dieser Parameter kann eine der folgenden ganzzahligen Konstanten sein:

iEsc-Konstante Ereignis
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 im Begriff, einen Aufruf seiner EndPage-Funktion zu verarbeiten.
DOCUMENTEVENT_ESCAPE GDI ist dabei, einen Aufruf seiner ExtEscape-Funktion zu verarbeiten.
DOCUMENTEVENT_QUERYFILTER Das ereignis DOCUMENTEVENT_QUERYFILTER 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 unmittelbar 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 seiner 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 seiner StartDoc-Funktion zu verarbeiten.
DOCUMENTEVENT_STARTPAGE GDI ist im Begriff, einen Aufruf seiner StartPage-Funktion zu verarbeiten.

cbIn

Vom Aufrufer bereitgestellte Größe des Puffers, auf den pvIn verweist, in Bytes.

[in] pvIn

Vom Aufrufer bereitgestellter Zeiger, dessen Verwendung vom für iEsc angegebenen Wert abhängig ist, wie folgt:

iEsc-Konstante pvIn-Inhalte
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 zeigt 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 die DEVMODEW-Struktur , die vom Aufrufer der ResetDC-Funktion bereitgestellt wird.
DOCUMENTEVENT_STARTDOCPOST pvIn verweist auf einen LONG-Wert, der den von der StartDoc-Funktion zurückgegebenen Druckauftragsbezeichner angibt.
DOCUMENTEVENT_STARTDOCPRE oder DOCUMENTEVENT_STARTDOC pvIn enthält die Adresse eines Zeigers auf eine DOCINFO-Struktur , die vom Aufrufer der StartDoc-Funktion bereitgestellt wird.
DOCUMENTEVENT_STARTPAGE Wird nicht verwendet.

cbOut

Wenn iEsc DOCUMENTEVENT_ESCAPE

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

Wenn iEsc DOCUMENTEVENT_QUERYFILTER

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

Für alle anderen iEsc-Werte

Wird nicht verwendet.

[out] pvOut

Von der Funktion bereitgestellter Zeiger auf einen Ausgabepuffer, dessen Verwendung vom für iEsc angegebenen Wert abhängt, wie folgt:

iEsc-Konstante pvOut-Inhalte
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 die ExtEscape-Funktion verwendet wird.
DOCUMENTEVENT_QUERYFILTER Vom Aufrufer bereitgestellter Zeiger auf den Puffer, der eine DOCEVENT_FILTER-Struktur enthält.
DOCUMENTEVENT_RESETDCPRE Zeiger auf eine vom Treiber bereitgestellte DEVMODEW-Struktur, die GDI anstelle der vom ResetDC-Funktionsaufrufer bereitgestellten Struktur verwendet. (Bei NULL verwendet GDI die vom Aufrufer bereitgestellte Struktur.)
Alle anderen iEsc-Werte Wird nicht verwendet.

Rückgabewert

Der Rückgabewert der Funktion ist von der für iEsc bereitgestellten Escape abhängig. Bei einigen Escapecodes wird der Rückgabewert nicht verwendet (siehe die zweite Liste der Werte). Wenn die Funktion einen Rückgabewert bereitstellt, muss es sich um einen der folgenden Werte handelt:

Rückgabecode Beschreibung
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.
DOCUMENTEVENT_UNSUPPORTED Der Treiber unterstützt den von iEsc identifizierten Escapecode nicht.

Hinweise

Eine Druckerschnittstellen-DLL kann optional eine DrvDocumentEvent-Funktion bereitstellen, um die Vor- oder Nachverarbeitung von GDI-Aufrufen durchzuführen, die dem Rendern eines Dokuments zugeordnet sind. Aufrufe der DrvDocumentEvent-Funktion erfolgen vom GDI-Client im Benutzermodus, wenn eine Anwendung Aufrufe an den GDI-Client durchführt.

Bei einem iEsc-Wert von DOCUMENTEVENT_QUERYFILTER kann der Spooler einen von DrvDocumentEvent zurückgegebenen DOCUMENTEVENT_SUCCESS Wert auf zwei Arten interpretieren, je nachdem, ob der Treiber bestimmte Elemente der DOCEVENT_FILTER-Struktur geändert hat. (Der pvOut-Parameter verweist auf diese Struktur.) Wenn der Spooler Arbeitsspeicher für eine Struktur dieses Typs zuweist, initialisiert er zwei Member dieser Struktur, cElementsReturned und cElementsNeeded, für bekannte Werte. Nachdem DrvDocumentEvent zurückgegeben wurde, bestimmt der Spooler, ob sich die Werte dieser Member geändert haben, und verwendet diese Informationen, um den DrvDocumentEvent-Rückgabewert zu interpretieren. In der folgenden Tabelle wird diese Situation zusammengefasst.

Rückgabewert Status von cElementsReturned, cElementsNeed Bedeutung
DOCUMENTEVENT_SUCCESS Der Treiber hat keine Änderung an beiden Membern vorgenommen. Der Spooler interpretiert diesen Rückgabewert als gleichwertig mit DOCUMENTEVENT_UNSUPPORTED. Der Spooler kann den Ereignisfilter nicht aus dem Treiber abrufen, sodass er drvDocumentEvent für alle Ereignisse weiterhin aufruft.
DOCUMENTEVENT_SUCCESS Der Treiber hat an ein oder beide Member geschrieben. Der Spooler akzeptiert diesen Rückgabewert ohne Interpretation. Wenn der Treiber nur in cElementsNeeded und cElementsReturned geschrieben hat, betrachtet der Spooler den Wert des unveränderten Members mit dem Wert 0. Der Spooler filtert alle Ereignisse heraus, die im aDocEventCall-Member von DOCEVENT_FILTER aufgeführt sind.
DOCUMENTEVENT_UNSUPPORTED Nicht zutreffend Der Treiber unterstützt DOCUMENTEVENT_QUERYFILTER nicht. Der Spooler kann den Ereignisfilter nicht aus dem Treiber abrufen, sodass er drvDocumentEvent für alle Ereignisse weiterhin aufruft.
DOCUMENTEVENT_FAILURE Nicht zutreffend Der Treiber unterstützt DOCUMENTEVENT_QUERYFILTER, ist jedoch ein interner Fehler aufgetreten. Der Spooler kann den Ereignisfilter nicht aus dem Treiber abrufen, sodass er drvDocumentEvent für alle Ereignisse weiterhin aufruft.

Wenn der Escapecodename kein Suffix hat oder mit PRE suffixiert ist, ruft der GDI-Client DrvDocumentEvent auf, bevor die Kernelmodus-GDI-Rendering-Engine aufgerufen wird. Wenn der Escapecodename mit POST versehen ist, ruft der GDI-Client DrvDocumentEvent auf, nachdem die Kernelmodus-GDI-Rendering-Engine zurückgegeben wurde.

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 DOCEVENT_CREATEDCPRE-Struktur .)

  • Wenn der Auftrag gepoolt wird, zeigt pvIn --> pszDevice auf den Namen des Druckerports.

Die DrvDocumentEvent-Funktion wird im Kontext des Benutzermodusaufrufers der GDI-Clientfunktion ausgeführt. Wenn das EMF-Spooling deaktiviert ist, kann die Funktion eine Benutzeroberfläche anzeigen. Beispielsweise kann die DrvDocumentEvent-Funktion für einen FAX-Treiber dem Benutzer ein Dialogfeld anzeigen, bevor die StartDoc-Funktion von GDI verarbeitet wird.

Die folgenden Einschränkungen gelten beim Ausführen einer 32-Bit-Anwendung unter einer 64-Bit-Version von Windows:

  • Die einzige GDI-Funktion, die DrvDocumentEvent aufrufen sollte, ist ExtEscape, und es sollten nur private Escapes verwendet werden.

  • DrvDocumentEvent-Aufrufe anderer GDI-Funktionen können zu undefiniertem Verhalten führen.

Anforderungen

Anforderung Wert
Zielplattform Desktop
Kopfzeile winddiui.h (include Winddiui.h)

Weitere Informationen

DOCEVENT_CREATEDCPRE

DOCEVENT_ESCAPE

DOCEVENT_FILTER