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）

另請參閱