drvDocumentEvent 函式 (winddiui.h)
印表機介面 DLL 的 DrvDocumentEvent 函式可以處理與列印文件相關聯的特定事件。
語法
int DrvDocumentEvent(
HANDLE hPrinter,
HDC hdc,
int iEsc,
ULONG cbIn,
[in] PVOID pvIn,
ULONG cbOut,
[out] PVOID pvOut
);
參數
hPrinter
呼叫端提供的印表機句柄。
hdc
呼叫端提供的裝置內容句柄，由 CreateDC 產生。如果 iEsc 設定為 DOCUMENTEVENT_CREATEDCPRE，則為零。 For restrictions on printing from a 32-bit application on a 64-bit version of Windows, see the Remarks section below.
iEsc
呼叫端提供的逸出程式代碼，識別要處理的事件。
For restrictions on printing from a 32-bit application on a 64-bit version of Windows, see the Remarks section below.
此參數可以是下列其中一個整數常數：
| iEsc 常數 | 事件 |
|---|---|
| DOCUMENTEVENT_ABORTDOC | GDI 即將處理其 AbortDoc 函式的呼叫。 |
| DOCUMENTEVENT_CREATEDCPOST | GDI 剛處理其 CreateDC 或 CreateIC 函式的呼叫。 除非先前已呼叫DrvDocumentEvent且iEsc設為 DOCUMENTEVENT_CREATEDCPRE，否則不應該使用此逸出程序代碼。 |
| DOCUMENTEVENT_CREATEDCPRE | GDI 即將處理其 CreateDC 或 CreateIC 函式的呼叫。 |
| DOCUMENTEVENT_DELETEDC | GDI 即將處理其 DeleteDC 函式的呼叫。 |
| DOCUMENTEVENT_ENDDOCPOST | GDI 剛剛處理對 EndDoc 函式的呼叫。 |
| DOCUMENTEVENT_ENDDOCPRE或DOCUMENTEVENT_ENDDOC | GDI 即將處理其 EndDoc 函式的呼叫。 |
| DOCUMENTEVENT_ENDPAGE | GDI 即將處理對 EndPage 函式的呼叫。 |
| DOCUMENTEVENT_ESCAPE | GDI 即將處理其 ExtEscape 函式的呼叫。 |
| DOCUMENTEVENT_QUERYFILTER | DOCUMENTEVENT_QUERYFILTER 事件代表多任務緩衝處理器查詢驅動程式的一份DOCUMENTEVENT_XXX 事件清單的機會，驅動程式會響應該事件。 此事件會在呼叫傳遞DOCUMENTEVENT_CREATEDCPRE事件的 DrvDocumentEvent 之前發出。 |
| DOCUMENTEVENT_RESETDCPOST | GDI 剛處理對 ResetDC 函式的呼叫。 除非先前呼叫DrvDocumentEvent且iEsc設為 DOCUMENTEVENT_RESETDCPRE，否則不應該使用此逸出程序代碼。 |
| DOCUMENTEVENT_RESETDCPRE | GDI 即將處理其 ResetDC 函式的呼叫。 |
| DOCUMENTEVENT_STARTDOCPOST | GDI 剛剛處理了 對 StartDoc 函式的呼叫。 |
| DOCUMENTEVENT_STARTDOCPRE或DOCUMENTEVENT_STARTDOC | GDI 即將處理其 StartDoc 函式的呼叫。 |
| DOCUMENTEVENT_STARTPAGE | GDI 即將處理其 StartPage 函式的呼叫。 |
cbIn
由呼叫端提供的大小，以位元組為單位，由 pvIn 指向的緩衝區。
[in] pvIn
呼叫端提供的指標，其用法取決於為 iEsc提供的值，如下所示：
| iEsc 常數 | pvIn 內容 |
|---|---|
| DOCUMENTEVENT_ABORTDOC | 未使用。 |
| DOCUMENTEVENT_CREATEDCPOST | pvIn 包含先前呼叫此函式中 pvOut 參數中所指定 DEVMODEW 結構的指標位址，其中 iEsc 參數設定為 DOCUMENTEVENT_CREATEDCPRE。 |
| DOCUMENTEVENT_CREATEDCPRE | pvIn 指向 DOCEVENT_CREATEDCPRE 結構。 |
| DOCUMENTEVENT_DELETEDC | 未使用。 |
| DOCUMENTEVENT_ENDDOCPOST | 未使用。 |
| DOCUMENTEVENT_ENDDOCPRE或DOCUMENTEVENT_ENDDOC | 未使用。 |
| DOCUMENTEVENT_ENDPAGE | 未使用。 |
| DOCUMENTEVENT_ESCAPE | pvIn 指向 DOCEVENT_ESCAPE 結構。 |
| DOCUMENTEVENT_QUERYFILTER | 與 DOCUMENTEVENT_CREATEDCPRE 相同。 |
| DOCUMENTEVENT_RESETDCPOST | pvIn 包含先前呼叫此函式中 pvOut 參數中所指定 DEVMODEW 結構的指標位址，其中 iEsc 參數已設定為 DOCUMENTEVENT_RESETDCPRE。 |
| DOCUMENTEVENT_RESETDCPRE | pvIn 包含 ResetDC 函式呼叫端所提供之 DEVMODEW 結構的指標位址。 |
| DOCUMENTEVENT_STARTDOCPOST | pvIn 指向 LONG，指定 StartDoc 函式所傳回的列印作業識別碼。 |
| DOCUMENTEVENT_STARTDOCPRE或DOCUMENTEVENT_STARTDOC | pvIn 包含 StartDoc 函式呼叫端所提供 DOCINFO 結構的指標位址。 |
| DOCUMENTEVENT_STARTPAGE | 未使用。 |
cbOut
如果 iEsc 為 DOCUMENTEVENT_ESCAPE
做為 ExtEscape 函式之 cbOutput 參數的函式提供值。
如果 iEsc 為 DOCUMENTEVENT_QUERYFILTER
由 pvOut 指向 之緩衝區指標的呼叫端提供大小，以位元組為單位。
針對所有其他 iEsc 值
未使用。
[out] pvOut
函式提供的輸出緩衝區指標，其用法取決於為 iEsc提供的值，如下所示：
| iEsc 常數 | pvOut 內容 |
|---|---|
| DOCUMENTEVENT_CREATEDCPRE | 驅動程式提供的 DEVMODEW 結構的指標，GDI 會使用此結構，而不是 CreateDC 呼叫端所提供的架構。 (如果 為 NULL，GDI 會使用呼叫端提供的 structure.) |
| DOCUMENTEVENT_ESCAPE | 緩衝區指標，做為 ExtEscape 函式的 lpszOutData 參數。 |
| DOCUMENTEVENT_QUERYFILTER | 呼叫端提供的緩衝區指標，其中包含 DOCEVENT_FILTER 結構。 |
| DOCUMENTEVENT_RESETDCPRE | 驅動程式提供的 DEVMODEW 結構的指標，GDI 會使用這個結構，而不是 ResetDC 函數呼叫端所提供的。 (如果 為 NULL，GDI 會使用呼叫端提供的 structure.) |
| 所有其他 iEsc 值 | 未使用。 |
傳回值
函式的傳回值取決於為 iEsc提供的逸出。 對於某些逸出碼，傳回值不會使用 (查看第二份值清單) 。 如果函式提供傳回值，它必須是下列其中一項：
| 傳回碼 | Description |
|---|---|
| DOCUMENTEVENT_FAILURE | 驅動程式支援 iEsc 所識別的逸出程式代碼，但發生失敗。 |
| DOCUMENTEVENT_SUCCESS | 驅動程式已成功處理 iEsc 所識別的逸出程式代碼。 |
| DOCUMENTEVENT_UNSUPPORTED | 驅動程式不支援 iEsc 所識別的逸出程式代碼。 |
備註
印表機介面 DLL 可以選擇性地提供DrvDocumentEvent函式，以執行與轉譯文件相關聯之 GDI 呼叫的前置處理或後置處理。 當應用程式呼叫 GDI 用戶端時，會從使用者模式 GDI 用戶端呼叫 DrvDocumentEvent 函式。
針對 DOCUMENTEVENT_QUERYFILTER 的 iEsc 值，多任務緩衝處理器可以使用兩種方式解譯 DrvDocumentEvent 所傳回的DOCUMENTEVENT_SUCCESS值，視驅動程式是否修改 了DOCEVENT_FILTER 結構的特定成員而定。 (pvOut 參數指向這個 structure.) 當多任務緩衝處理器為此類型的結構配置記憶體時，它會將這個結構的兩個成員 cElementsReturned 和 cElementsNeeded 初始化為已知值。 DrvDocumentEvent 傳回之後，多任務緩衝處理程式會判斷這些成員的值是否已變更，並使用該資訊來解譯DrvDocumentEvent傳回值。 下表摘要說明這種情況。
| 傳回值 | cElementsReturned、cElementsNeeded 的狀態 | 意義 |
|---|---|---|
| DOCUMENTEVENT_SUCCESS | 驅動程式未變更任一成員。 | 多任務緩衝處理器會將這個傳回值解譯為相當於DOCUMENTEVENT_UNSUPPORTED。 多任務緩衝處理程式無法從驅動程式擷取事件篩選器，因此它會針對所有事件持續呼叫 DrvDocumentEvent 。 |
| DOCUMENTEVENT_SUCCESS | 驅動程式寫入一或兩個成員。 | 多任務緩衝處理程式會接受此傳回值，而不需解譯。 如果驅動程式只寫入其中一個 cElementsNeeded 和 cElementsReturned，多任務緩衝處理器會將未變更的成員視為值為零。 多任務緩衝處理程式會篩選出DOCEVENT_FILTERaDocEventCall 成員中列出的所有事件。 |
| DOCUMENTEVENT_UNSUPPORTED | 不適用 | 驅動程式不支援DOCUMENTEVENT_QUERYFILTER。 多任務緩衝處理程式無法從驅動程式擷取事件篩選器，因此它會針對所有事件持續呼叫 DrvDocumentEvent 。 |
| DOCUMENTEVENT_FAILURE | 不適用 | 驅動程式支援DOCUMENTEVENT_QUERYFILTER，但發生內部錯誤。 多任務緩衝處理程式無法從驅動程式擷取事件篩選器，因此它會針對所有事件持續呼叫 DrvDocumentEvent 。 |
如果逸出程式代碼名稱沒有後綴，或後綴為 PRE，GDI 用戶端會在呼叫內核模式 GDI 轉譯引擎之前呼叫 DrvDocumentEvent 。 如果逸出程式代碼名稱後綴為POST，GDI用戶端會在核心模式 GDI 轉譯引擎傳回之後呼叫 DrvDocumentEvent 。
如果 iEsc 參數中提供的逸出程式代碼DOCUMENTEVENT_CREATEDCPRE，則適用下列規則：
如果作業直接傳送到印表機而不進行多任務緩衝處理， pvIn --> pszDevice 會指向印表機名稱。 (如需詳細資訊，請參閱 DOCEVENT_CREATEDCPRE 結構。)
如果作業正在多任務緩衝處理， pvIn --> pszDevice 會指向印表機埠名稱。
DrvDocumentEvent 函式會在 GDI 用戶端函式的使用者模式呼叫端內容中執行。 停用 EMF 多任務緩衝處理時，函式可以顯示使用者介面。 例如，在處理 GDI 的 StartDoc 函式之前，傳真驅動程式的 DrvDocumentEvent 函式可能會向使用者顯示對話方塊。
在 64 位版本的 Windows 上執行 32 位應用程式時，適用下列限制：
DrvDocumentEvent 應該呼叫的唯一 GDI 函式是 ExtEscape，而且只應該使用私用逸出。
DrvDocumentEvent 呼叫其他 GDI 函式可能會產生未定義的行為。
規格需求
| 需求 | 值 |
|---|---|
| 目標平台 | 桌面 |
| 標頭 | winddiui.h (包含Winddiui.h) |