共用方式為


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 位版本的 Windows 上列印 32 位應用程式的限制,請參閱。

iEsc

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

持續性 Event
DOCUMENTEVENT_ABORTDOC
GDI 即將處理其 AbortDoc 函式的呼叫。
DOCUMENTEVENT_CREATEDCPOST
GDI 剛處理其 CreateDC CreateIC 函式的呼叫。
除非先前已呼叫 DocumentEvent 且 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事件的 DocumentEvent 之前發出。
DOCUMENTEVENT_RESETDCPOST
GDI 剛剛處理其 ResetDC 函式的呼叫。
除非先前已呼叫 DocumentEvent 且 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 呼叫端所提供的 結構。 (If Null,GDI 會使用呼叫端提供的 結構。
DOCUMENTEVENT_ESCAPE
做為 ExtEscape 之 lpszOutData 參數之緩衝區的 指標。
DOCUMENTEVENT_QUERYFILTER
緩衝區指標,其中包含 Windows 驅動程式開發工具組 記載的DOCEVENT_FILTER結構。
DOCUMENTEVENT_RESETDCPRE
驅動程式提供的 DEVMODE 結構的指標,GDI 會使用此結構,而不是 ResetDC 呼叫端所提供的 結構。 (If Null,GDI 會使用呼叫端提供的 結構。

傳回值

函式的傳回值取決於 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 的傳回值。

備註

針對 iEsc 值DOCUMENTEVENT_QUERYFILTER,多工緩衝處理常式可以透過兩種方式解譯 DocumentEvent 回的DOCUMENTEVENT_SUCCESS值,視驅動程式是否修改了DOCEVENT_FILTER結構的某些成員而定(如 Windows 驅動程式開發工具組 中所述 )。 (pvOut 參數指向這個 結構。當多工緩衝處理器配置此型別結構的記憶體時,它會將這個結構的 兩個成員 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,則適用下列規則:

注意

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

需求

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

另請參閱