DrvDocumentEvent-Funktion (winddiui.h)
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) |