IPrintOemUI2::D ocumentEvent メソッド (prcomoem.h)

[アーティクル]
03/14/2023

IPrintOemUI2::DocumentEventメソッドを使用すると、UI プラグインは、コアドライバー UI モジュールの DrvDocumentEvent DDI の既定の実装を置き換えることができます。

構文

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

パラメーター

hPrinter

呼び出し元が指定したプリンターハンドル。

hdc

CreateDC 呼び出しによって生成される、呼び出し元から提供されるデバイスコンテキストハンドル。 iEsc がDOCUMENTEVENT_CREATEDCPRE場合、これは 0 です。

iEsc

処理するイベントを識別する呼び出し元指定のエスケープコード。このパラメーターには、次のいずれかの整数定数を指定できます。

エスケープコード	意味
DOCUMENTEVENT_ABORTDOC	GDI では、 AbortDoc 関数の呼び出しを処理します。
DOCUMENTEVENT_CREATEDCPOST	GDI は、 CreateDC または CreateIC 関数の呼び出しを処理したばかりです。 iEsc が DOCUMENTEVENT_CREATEDCPRE に設定された DrvDocumentEvent の以前の呼び出しがない限り、このエスケープコードを使用しないでください。
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 関数の呼び出しを処理したばかりです。 iEsc を DOCUMENTEVENT_RESETDCPRE に設定した DrvDocumentEvent の以前の呼び出しがない限り、このエスケープコードを使用しないでください。
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 には、ResetDC の呼び出し元によって提供される DEVMODEW 構造体へのポインターのアドレスが含まれます (Microsoft Windows SDKドキュメントで説明します)。
DOCUMENTEVENT_STARTDOCPOST	pvIn は、 StartDoc によって返される印刷ジョブ識別子を指定する LONG を指します (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 に指定された値に依存します。 CreateDC、 ExtEscape、 ResetDC については、Windows SDK のドキュメントで説明されています。

iEsc 定数	pvOut 内容
DOCUMENTEVENT_CREATEDCPRE	ドライバーによって提供される DEVMODEW 構造体へのポインター。 GDI は、CreateDC 呼び出し元によって提供される構造体の代わりにを使用します。 ( NULL の場合、GDI は呼び出し元が指定した構造体を使用します)。
DOCUMENTEVENT_ESCAPE	ExtEscape の lpszOutData パラメーターとして使用されるバッファーポインター。
DOCUMENTEVENT_QUERYFILTER	DOCEVENT_FILTER構造体を含むバッファーへの呼び出し元から提供されるポインター。
DOCUMENTEVENT_RESETDCPRE	ドライバーによって提供される DEVMODEW 構造体へのポインター。 GDI は ResetDC 呼び出し元によって提供される構造体ではなくを使用します。 ( NULL の場合、GDI は呼び出し元が指定した構造体を使用します)。
その他のすべての 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 呼び出してイベントの追加処理を処理します。

このメソッドが DOCUMENTEVENT_QUERYFILTER の iEsc パラメーターの値を使用して呼び出され、*piResult == DOCUMENTEVENT_SUCCESS でを返す場合、スプーラーは、DOCEVENT_FILTER構造体の特定のメンバーが値を変更したかどうかに応じて、2 つの方法のいずれかでこの値を解釈できます。詳細については、 DrvDocumentEvent の「解説」セクションを参照してください。

DOCUMENTEVENT_QUERYFILTER イベントが発生すると、コアドライバーは、インストールされた順序でプラグインを呼び出します。そのうちの 1 つがS_OKを返すまで、またはすべてのプラグインが呼び出され、どのプラグインもS_OK返されないまで呼び出されます。この方法では、最大 1 つのプラグインでDOCUMENTEVENT_QUERYFILTER イベントの処理が許可され、指定したフィルターがプラグインチェーン内のすべてのプラグインに適用されます。

IPrintOemUI2 インターフェイスを実装しているが、メソッドをサポートIPrintOemUI2::DocumentEventする必要がないプラグインライターの場合、このメソッドは iEsc のすべての値のE_NOTIMPLを返す必要があります。このメソッドを実装する必要がある場合は、 iEsc のすべての値のS_OKが返されます。これにより、このメソッドが関連するイベントを処理したことをコアドライバーに通知します。コアドライバーは、このメソッドが piResult に配置する値を DrvDocumentEvent DDI の戻り値として使用します。