DrvDocumentEvent 関数 (winddiui.h)

[アーティクル]
03/08/2024

プリンターインターフェイス DLL の DrvDocumentEvent 関数は、ドキュメントの印刷に関連する特定のイベントを処理できます。

構文

int DrvDocumentEvent(
        HANDLE hPrinter,
        HDC    hdc,
        int    iEsc,
        ULONG  cbIn,
  [in]  PVOID  pvIn,
        ULONG  cbOut,
  [out] PVOID  pvOut
);

パラメーター

hPrinter

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

hdc

呼び出し元が指定したデバイスコンテキストハンドル。 CreateDC によって生成されます。 iEsc が DOCUMENTEVENT_CREATEDCPRE に設定されている場合、ゼロになります。 64 ビットバージョンの Windows での 32 ビットアプリケーションからの印刷に関する制限については、以下の 「備考 」セクションを参照してください。

iEsc

処理するイベントを識別する呼び出し元指定のエスケープコード。

64 ビットバージョンの Windows での 32 ビットアプリケーションからの印刷に関する制限については、以下の 「備考 」セクションを参照してください。

このパラメーターには、次のいずれかの整数定数を指定できます。

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 が指すバッファーの呼び出し元が指定したサイズ (バイト単位)。

[in] 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 構造体へのポインターのアドレスが含まれています。
DOCUMENTEVENT_STARTDOCPOST	pvIn は、 StartDoc 関数によって返される印刷ジョブ識別子を指定する LONG を指します。
DOCUMENTEVENT_STARTDOCPREまたはDOCUMENTEVENT_STARTDOC	pvIn には、StartDoc 関数の呼び出し元によって提供される DOCINFO 構造体へのポインターのアドレスが含まれています。
DOCUMENTEVENT_STARTPAGE	使用されていません。

cbOut

iEsc がDOCUMENTEVENT_ESCAPE

ExtEscape 関数の cbOutput パラメーターとして使用される関数提供の値。

iEsc がDOCUMENTEVENT_QUERYFILTER

pvOut によるへのバッファーポインターの呼び出し元から指定されたサイズ (バイト単位)。

その他すべての iEsc 値

使用されていません。

[out] pvOut

出力バッファーへの関数提供ポインター。その使用は、 次のように iEsc に指定された値に依存します。

iEsc 定数	pvOut コンテンツ
DOCUMENTEVENT_CREATEDCPRE	ドライバーが提供する DEVMODEW 構造体へのポインター。この構造体は、 CreateDC 呼び出し元によって提供されるのではなく、GDI によって使用されます。 ( NULL の場合、GDI は呼び出し元から提供された構造体を使用します)。
DOCUMENTEVENT_ESCAPE	ExtEscape 関数の lpszOutData パラメーターとして使用されるバッファーポインター。
DOCUMENTEVENT_QUERYFILTER	DOCEVENT_FILTER構造体を含むバッファーへの呼び出し元から提供されたポインター。
DOCUMENTEVENT_RESETDCPRE	ドライバーが提供する DEVMODEW 構造体へのポインター。これは、ResetDC 関数の呼び出し元によって提供されるのではなく GDI によって使用されます。 ( NULL の場合、GDI は呼び出し元から提供された構造体を使用します)。
その他のすべての iEsc 値	使用されていません。

戻り値

関数の戻り値は、 iEsc に指定されたエスケープに依存します。一部のエスケープコードでは、戻り値は使用されません (2 番目の値の一覧を参照してください)。関数が戻り値を提供する場合は、次のいずれかである必要があります。

リターンコード	説明
DOCUMENTEVENT_FAILURE	ドライバーは、iEsc によって識別されるエスケープコードをサポートしていますが、エラーが発生しました。
DOCUMENTEVENT_SUCCESS	ドライバーは、 iEsc によって識別されるエスケープコードを正常に処理しました。
DOCUMENTEVENT_UNSUPPORTED	ドライバーは、 iEsc によって識別されるエスケープコードをサポートしていません。

注釈

プリンターインターフェイス DLL は、必要に応じて、ドキュメントのレンダリングに関連付けられた GDI 呼び出しの前処理または後処理を実行する DrvDocumentEvent 関数を提供できます。 DrvDocumentEvent 関数の呼び出しは、アプリケーションが GDI クライアントを呼び出すときに、ユーザーモードの GDI クライアントから行われます。

DOCUMENTEVENT_QUERYFILTERの iEsc 値の場合、スプーラーは、ドライバーがDOCEVENT_FILTER構造体の特定のメンバーを変更したかどうかに応じて、 DrvDocumentEvent によって返される DOCUMENTEVENT_SUCCESS 値を 2 つの方法で解釈できます。 ( pvOut パラメーターは、この構造体を指します)。スプーラーは、この型の構造体にメモリを割り当てると、この構造体の 2 つのメンバー cElementsReturned と cElementsNeeded を既知の値に初期化します。 DrvDocumentEvent が返された後、スプーラーはこれらのメンバーの値が変更されたかどうかを判断し、その情報を使用して DrvDocumentEvent の戻り値を解釈します。この状況を次の表にまとめます。

戻り値	cElementsReturned、cElementsNeeded の状態	意味
DOCUMENTEVENT_SUCCESS	ドライバーは、どちらのメンバーにも変更を加えなくなりました。	スプーラーは、この戻り値をDOCUMENTEVENT_UNSUPPORTEDと等価と解釈します。スプーラーはドライバーからイベントフィルターを取得できないため、すべてのイベントに対して DrvDocumentEvent を呼び出しても保持されます。
DOCUMENTEVENT_SUCCESS	ドライバーは、一方または両方のメンバーに書き込んだ。	スプーラーは、解釈なしでこの戻り値を受け入れます。ドライバーが cElementsNeeded と cElementsReturned の 1 つだけに書き込んだ場合、スプーラーは変更されていないメンバーの値が 0 であると見なします。スプーラーは、DOCEVENT_FILTERの aDocEventCall メンバーにリストされているすべてのイベントを除外します。
DOCUMENTEVENT_UNSUPPORTED	適用なし	ドライバーはDOCUMENTEVENT_QUERYFILTERをサポートしていません。スプーラーはドライバーからイベントフィルターを取得できないため、すべてのイベントに対して DrvDocumentEvent を呼び出しても保持されます。
DOCUMENTEVENT_FAILURE	適用なし	ドライバーはDOCUMENTEVENT_QUERYFILTERをサポートしていますが、内部エラーが発生しました。スプーラーはドライバーからイベントフィルターを取得できないため、すべてのイベントに対して DrvDocumentEvent を呼び出しても保持されます。

エスケープコード名にサフィックスがない場合、または PRE にサフィックスが付いている場合、GDI クライアントはカーネルモード GDI レンダリングエンジンを呼び出す直前に DrvDocumentEvent を呼び出します。エスケープコード名のサフィックスに POST が付いている場合、GDI クライアントは、カーネルモードの GDI レンダリングエンジンから戻った直後に DrvDocumentEvent を呼び出します。

iEsc パラメーターで指定されたエスケープコードがDOCUMENTEVENT_CREATEDCPRE場合は、次の規則が適用されます。

ジョブがスプールなしでプリンターに直接送信される場合、 pvIn --> pszDevice はプリンター名を指します。 (詳細については、 DOCEVENT_CREATEDCPRE 構造体を参照してください)。
ジョブがスプールされている場合、 pvIn --> pszDevice はプリンター・ポート名を指します。

DrvDocumentEvent 関数は、GDI クライアント関数のユーザーモード呼び出し元のコンテキストで実行されます。 EMF スプールが使用不可の場合、この関数はユーザー・インターフェースを表示できます。たとえば、FAX ドライバーの DrvDocumentEvent 関数は、GDI の StartDoc 関数が処理される前に、ユーザーにダイアログボックスを表示する場合があります。

64 ビットバージョンの Windows で 32 ビットアプリケーションを実行する場合は、次の制限が適用されます。

DrvDocumentEvent が呼び出す必要がある GDI 関数は ExtEscape のみで、プライベートエスケープのみを使用する必要があります。
他の GDI 関数に対する DrvDocumentEvent 呼び出しでは、未定義の動作が発生する可能性があります。

要件

要件	値
対象プラットフォーム	デスクトップ
Header	winddiui.h (Winddiui.h を含む)

こちらもご覧ください

DOCEVENT_CREATEDCPRE

DOCEVENT_ESCAPE

DOCEVENT_FILTER

次の方法で共有