IPrintOemUI2：:D ocumentEvent 方法 (prcomoem.h)

發行項
03/01/2024

方法 IPrintOemUI2::DocumentEvent 可讓 UI 外掛程式取代 DrvDocumentEvent DDI 的核心驅動程式 UI 模組預設實作。

語法

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

參數

hPrinter

呼叫端提供的印表機句柄。

hdc

呼叫端提供的裝置內容句柄，由 CreateDC 呼叫產生。如果 iEsc 是DOCUMENTEVENT_CREATEDCPRE，這會是零。

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 事件清單的機會。此事件會在呼叫通過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 指向的緩衝區。

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 包含重設 (DC 呼叫者所提供之 DEVMODEW 結構的指標位址，Microsoft Windows SDK 檔) 中所述。
DOCUMENTEVENT_STARTDOCPOST	pvIn 指向 LONG，指定 StartDoc 所傳回的列印作業標識碼 (Windows SDK 檔) 中所述。
DOCUMENTEVENT_STARTDOCPRE 或 DOCUMENTEVENT_STARTDOC	pvIn 包含 StartDoc 呼叫端所提供 DOCINFO 結構的指標位址， (Windows SDK 檔) 中所述。
DOCUMENTEVENT_STARTPAGE	未使用。

cbOut

如果 iEsc DOCUMENTEVENT_ESCAPE：

函式提供的值，做為 ExtEscape 的 cbOutput 參數。

如果 iEsc DOCUMENTEVENT_QUERYFILTER：

pvOut 所提供緩衝區指標的位元元組大小。

針對所有其他 iEsc 值：

未使用。

pvOut

函式提供的輸出緩衝區指標，其用途取決於提供給 iEsc的值，如下所示。 Windows SDK 文件說明 CreateDC、ExtEscape 和 ResetDC。

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 值	未使用。

piResult

接收下列其中一個值的記憶體位置指標：

傳回值	定義
DOCUMENTEVENT_FAILURE	驅動程式支援 iEsc 所識別的逸出程式代碼，但發生失敗。
DOCUMENTEVENT_SUCCESS	驅動程式已成功處理 iEsc 所識別的逸出程式代碼。另請參閱一節以取得詳細資訊。
DOCUMENTEVENT_UNSUPPORTED	驅動程式不支援 iEsc 所識別的逸出程式代碼。

傳回值

這個方法應該會傳回下列其中一個值。如需詳細資訊，請參閱＜備註＞一節。

傳回碼	描述
S_OK	UI 外掛程式會實作這個方法。
E_NOTIMPL	UI 外掛程式不會實作這個方法。

備註

使用者介面外掛程式的 IPrintOemUI2::DocumentEvent 方法會執行與使用者模式印表機介面 DLL 所匯出之 DrvDocumentEvent DDI 相同的作業類型。如需檔事件及其處理方式的相關信息，請參閱 DrvDocumentEvent DDI的描述。

如果您提供使用者介面外掛程式，印表機驅動程式的DrvDocumentEvent DDI 會呼叫 IPrintOemUI2::DocumentEvent 方法。 DrvDocumentEvent DDI 會針對指定的事件執行自己的處理，然後呼叫 IPrintOemUI2::DocumentEvent 方法來處理事件的其他處理。

使用 iEsc 參數的值DOCUMENTEVENT_QUERYFILTER呼叫此方法，並使用 *piResult == DOCUMENTEVENT_SUCCESS傳回時，多任務緩衝處理器可以使用兩種方式之一來解譯此值，視 DOCEVENT_FILTER 結構的特定成員是否變更值而定。如需詳細資訊，請參閱 DrvDocumentEvent的一節。

當引發DOCUMENTEVENT_QUERYFILTER事件時，核心驅動程式會依其安裝的順序呼叫外掛程式，直到其中一個外掛程式傳回S_OK，或直到呼叫所有外掛程式，且所有外掛程式都不會傳回S_OK。如此一來，最多允許一個外掛程式處理DOCUMENTEVENT_QUERYFILTER事件，而它指定的篩選會套用至外掛程式鏈結中的所有外掛程式。

對於實作 IPrintOemUI2 介面但不需要支援 IPrintOemUI2::DocumentEvent 方法的外掛程式寫入器，這個方法應該針對 iEsc 的所有值傳回E_NOTIMPL。如果您需要實作這個方法，它應該會針對 iEsc的所有值傳回S_OK。這會向核心驅動程式發出訊號，指出這個方法已處理相關的事件。核心驅動程式會使用這個方法放在 piResult 中的值作為 DrvDocumentEvent DDI 的傳回值。