DocumentEvent 函式

  • 發行項

DocumentEvent函式是與列印檔案相關聯的事件事件處理常式。

語法

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

參數

hPrinter [in]

印表機物件的控制碼。 使用 OpenPrinter 或 AddPrinter 函式來擷取印表機控制碼。

hdc [in]

由 CreateDC呼叫所產生的裝置內容控制碼。 如果 iEsc 設定為 DOCUMENTEVENT_CREATEDCPRE，則為零。 如需從 64 位版本的 32 位應用程式列印Windows的限制，請參閱。

iEsc

識別要處理之事件的逸出程式碼。 此參數可以是下列其中一個整數常數。

常數 事件
DOCUMENTEVENT_ABORTDOC
 GDI 即將處理 其 AbortDoc 函式的呼叫。
DOCUMENTEVENT_CREATEDCPOST
 GDI 剛處理其 CreateDC 或 CreateIC 函式的呼叫。
除非已將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 事件清單的機會。驅動程式將回應的 XXX 事件清單。 這個事件會在呼叫傳遞DOCUMENTEVENT_CREATEDCPRE事件的 DocumentEvent 之前發出。
DOCUMENTEVENT_RESETDCPOST
 GDI 剛處理其 ResetDC 函式的呼叫。
除非已將iEsc設定為 DOCUMENTEVENT_RESETDCPRE，否則不應該使用此逸出程式碼。
DOCUMENTEVENT_RESETDCPRE
 GDI 即將處理其 ResetDC 函式的呼叫。
DOCUMENTEVENT_STARTDOCPOST
 GDI 剛處理其 StartDoc 函式的呼叫。
DOCUMENTEVENT_STARTDOCPRE或DOCUMENTEVENT_STARTDOC
 GDI 即將處理其 StartDoc 函式的呼叫。
DOCUMENTEVENT_STARTPAGE
 GDI 即將處理其 StartPage 函式的呼叫。

cbIn

pvIn所指向之緩衝區的大小，以位元組為單位。

pvIn [in]

緩衝區的指標。 緩衝區包含的內容取決於 iEsc的值，如下表所示。

常數 pvin 內容
DOCUMENTEVENT_ABORTDOC
 未使用。
DOCUMENTEVENT_CREATEDCPOST
 pvIn包含先前呼叫此函式中pvOut參數中所指定DEVMODE結構的指標位址，iEsc參數已設定為 DOCUMENTEVENT_CREATEDCPRE。
DOCUMENTEVENT_CREATEDCPRE
 pvIn指向Windows驅動程式開發工具組中所記載的DOCEVENT_CREATEDCPRE結構。
DOCUMENTEVENT_DELETEDC
 未使用。
DOCUMENTEVENT_ENDDOCPOST
 未使用。
DOCUMENTEVENT_ENDDOCPRE或DOCUMENTEVENT_ENDDOC
 未使用。
DOCUMENTEVENT_ENDPAGE
 未使用。
DOCUMENTEVENT_ESCAPE
 pvIn指向Windows驅動程式開發工具組中所記載的DOCEVENT_ESCAPE結構。
DOCUMENTEVENT_QUERYFILTER
 與 DOCUMENTEVENT_CREATEDCPRE 相同。
DOCUMENTEVENT_RESETDCPOST
 pvIn包含先前呼叫此函式中pvOut參數中所指定DEVMODE結構的指標位址，其中iEsc參數已設定為 DOCUMENTEVENT_RESETDCPRE。
DOCUMENTEVENT_RESETDCPRE
 pvIn包含ResetDC呼叫端所提供之 DEVMODE結構的指標位址。
DOCUMENTEVENT_STARTDOCPOST
 pvIn 指向 LONG，指定 StartDoc傳回的列印工作識別碼。
DOCUMENTEVENT_STARTDOCPRE或DOCUMENTEVENT_STARTDOC
 pvIn包含StartDoc呼叫端所提供DOCINFO結構的指標位址。
DOCUMENTEVENT_STARTPAGE
 未使用。
*cbOut*
值 意義
IDOCUMENTEVENT_QUERYFILTER pvOut所指向緩衝區指標的大小，以位元組為單位。
DOCUMENTEVENT_ESCAPE 值，做為ExtEscape的cbOutput參數。
針對所有其他值 未使用iEsc。

pvOut [out]

緩衝區的指標。 緩衝區的內容取決於為 iEsc提供的值，如下表所示。

常數 pvOut 內容
DOCUMENTEVENT_CREATEDCPRE
 驅動程式提供的 DEVMODE 結構的指標，GDI 會使用該結構，而不是 CreateDC 呼叫端所提供的。 (如果 為 Null，GDI 會使用呼叫端提供的 structure.)
DOCUMENTEVENT_ESCAPE
 做為ExtEscape之 lpszOutData參數的緩衝區指標。
DOCUMENTEVENT_QUERYFILTER
 緩衝區的指標，其中包含Windows驅動程式開發工具組中所記載的DOCEVENT_FILTER結構。
DOCUMENTEVENT_RESETDCPRE
 驅動程式提供的 DEVMODE 結構的指標，GDI 會使用該結構，而不是 ResetDC 呼叫端所提供的。 (如果 為 Null，GDI 會使用呼叫端提供的 structure.)

傳回值

函式的傳回值取決於為 iEsc提供的逸出。 對於某些逸出碼，不會使用傳回值， (請參閱下列) 。 如果函式提供傳回值，它必須是下列其中一項。

傳回值 意義
DOCUMENTEVENT_FAILURE 驅動程式支援 iEsc所識別的逸出程式碼，但發生失敗。
DOCUMENTEVENT_SUCCESS 驅動程式已成功處理 iEsc所識別的逸出程式碼。
DOCUMENTEVENT_UNSUPPORTED 驅動程式不支援 iEsc所識別的逸出程式碼。

下列清單指出哪些逸出程式碼需要傳回值，且不需要傳回值，並說明DOCUMENTEVENT_SUCCESS、DOCUMENTEVENT_FAILURE和DOCUMENTEVENT_UNSUPPORTED傳回碼的意義。

傳回值 意義
DOCUMENTEVENT_ABORTDOC 未使用傳回值，不應讀取。
DOCUMENTEVENT_CREATEDCPOST 未使用傳回值，不應讀取。
DOCUMENTEVENT_CREATEDCPRE DOCUMENTEVENT_FAILURE - GDI 不會建立裝置內容或資訊內容，並提供 CreateDC 或 CreateIC的傳回值 0。
DOCUMENTEVENT_DELETEDC 未使用傳回值，不應讀取。
DOCUMENTEVENT_ENDDOCPOST 未使用傳回值，不應讀取。
DOCUMENTEVENT_ENDDOCPRE或DOCUMENTEVENT_ENDDOC 未使用傳回值，不應讀取。
DOCUMENTEVENT_ENDPAGE 未使用傳回值，不應讀取。
DOCUMENTEVENT_ESCAPE 未使用傳回值，不應讀取。
DOCUMENTEVENT_QUERYFILTER 請參閱＜備註＞。
DOCUMENTEVENT_RESETDCPOST 未使用傳回值，不應讀取。
DOCUMENTEVENT_RESETDCPRE DOCUMENTEVENT_FAILURE - GDI 不會重設裝置內容，並提供 ResetDC的傳回值 0。
DOCUMENTEVENT_STARTDOCPOST DOCUMENTEVENT_FAILURE - GDI 會呼叫 AbortDoc 來停止檔，然後提供 StartDoc的傳回值SP_ERROR。
DOCUMENTEVENT_STARTDOCPRE或DOCUMENTEVENT_STARTDOC DOCUMENTEVENT_FAILURE - GDI 不會開機檔案，並提供 StartDoc的傳回值SP_ERROR。
DOCUMENTEVENT_STARTPAGE DOCUMENTEVENT_FAILURE - GDI 不會啟動頁面，並提供 StartPage SP_ERROR的傳回值。

備註

針對 DOCUMENTEVENT_QUERYFILTER 的iEsc值，多工緩衝處理常式可以兩種方式解譯DocumentEvent所傳回的DOCUMENTEVENT_SUCCESS值，視驅動程式是否修改了DOCEVENT_FILTER結構的某些成員， (Windows驅動程式開發工具組中記載) 。 (pvOut 參數指向這個 structure.) 當多工緩衝處理器為此類型的結構配置記憶體時，它會將這個結構的兩個成員 cElementsReturned 和 cElementsNeeded初始化為已知值。 DocumentEvent傳回之後，多工緩衝處理常式會判斷這些成員的值是否已變更，並使用該資訊來解譯DocumentEvent傳回值。 下表摘要說明這種情況。

傳回值 cElementsReturned 和 cElementsNeeded 的狀態 意義
DOCUMENTEVENT_SUCCESS
 驅動程式不會變更任一成員。
 多工緩衝處理常式會將這個傳回值解譯為相當於 DOCUMENTEVENT_UNSUPPORTED。 多工緩衝處理常式無法從驅動程式擷取事件篩選準則，因此它會保存在所有事件的 呼叫 DocumentEvent 中。
DOCUMENTEVENT_SUCCESS
 驅動程式寫入一或兩個成員。
 多工緩衝處理會接受這個傳回值，而不需要解譯。 如果驅動程式只寫入其中一個 cElementsNeeded 和 cElementsReturned，則多工緩衝處理常式會將未變更的成員視為值為零。
多工緩衝處理常式會篩選出DOCEVENT_FILTER (aDocEventCall成員中列出的所有事件，這些事件記載于Windows驅動程式開發工具組) 中。
DOCUMENTEVENT_UNSUPPORTED
 不適用
 驅動程式不支援DOCUMENTEVENT_QUERYFILTER。
多工緩衝處理常式無法從驅動程式擷取事件篩選準則，因此它會保存在所有事件的 呼叫 DocumentEvent 中。
DOCUMENTEVENT_FAILURE
 不適用
 驅動程式支援DOCUMENTEVENT_QUERYFILTER，但發生內部錯誤。
多工緩衝處理常式無法從驅動程式擷取事件篩選準則，因此它會保存在所有事件的 呼叫 DocumentEvent 中。

如果 iEsc 參數中提供的逸出程式碼DOCUMENTEVENT_CREATEDCPRE，則適用下列規則：

  • 如果作業直接傳送至印表機而不進行多工緩衝處理，pvIn-pszDevice > 會指向印表機名稱。 (如需詳細資訊，請參閱Windows 驅動程式開發工具組.) 中DOCEVENT_CREATEDCPRE結構的檔
  • 如果作業正在多工緩衝處理，pvIn-pszDevice > 會指向印表機埠名稱。

注意

在 64 位版本的 Windows上執行 32 位應用程式時，適用下列限制。 DocumentEvent應該呼叫的唯一 GDI 函式是ExtEscape，而且應該只使用私用逸出。 DocumentEvent 對其他 GDI 函式的呼叫可能會產生未定義的行為。

規格需求

需求 值
最低支援的用戶端
 Windows Vista [僅限傳統型應用程式]
最低支援的伺服器
 Windows Server 2008 [僅限傳統型應用程式]
標頭
Winspool.h (包含 Windows.h)
Unicode 與 ANSI 名稱
 DocumentEventW (Unicode) 和 DocumentEventA (ANSI)

另請參閱

列印

列印多工緩衝處理器 API 函式

Windows驅動程式開發工具組