DrvDocumentEvent 関数 (winddiui.h)
プリンター インターフェイス 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 に設定されている場合は 0 になります。 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 構造体へのポインター。GDI は、CreateDC 呼び出し元によって提供される構造体の代わりに使用されます。 (NULL 場合、GDI は呼び出し元が指定した構造体を使用します)。 |
| DOCUMENTEVENT_ESCAPE | ExtEscape 関数の lpszOutData パラメーターとして使用されるバッファー ポインター。 |
| DOCUMENTEVENT_QUERYFILTER | DOCEVENT_FILTER 構造体を含むバッファーへの呼び出し元から指定されたポインター。 |
| DOCUMENTEVENT_RESETDCPRE | ドライバーが提供する DEVMODEW 構造体へのポインター。GDI は、ResetDC 関数呼び出し元によって提供される構造体の代わりに使用されます。 (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 パラメーターはこの構造体を指します。スプーラーは、この型の構造体にメモリを割り当てるときに、cElementsReturned と cElementsNeeded、この構造体の 2 つのメンバーを既知の値に初期化します。 DrvDocumentEvent 戻った後、スプーラーはこれらのメンバーの値が変更されたかどうかを判断し、その情報を使用して、DrvDocumentEvent 戻り値を解釈します。 この状況を次の表にまとめます。
| 戻り値 | cElementsReturned、cElementsNeeded の状態 | 意味 |
|---|---|---|
| DOCUMENTEVENT_SUCCESS | ドライバーは、どちらのメンバーにも変更を加えなくなりました。 | スプーラーは、この戻り値をDOCUMENTEVENT_UNSUPPORTEDと同等と解釈します。 スプーラーはドライバーからイベント フィルターを取得できないため、すべてのイベントの DrvDocumentEvent 呼び出し中に保持されます。 |
| DOCUMENTEVENT_SUCCESS | ドライバーが一方または両方のメンバーに書き込んだ。 | スプーラーは、解釈なしでこの戻り値を受け入れます。 ドライバーが cElementsNeeded のいずれかに書き込み、cElementsReturned をした場合、スプーラーは変更されていないメンバーの値が 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のみであり、プライベート エスケープのみを使用する必要があります。
DrvDocumentEvent 他の GDI 関数の呼び出し、未定義の動作が発生する可能性があります。
必要条件
| 要件 | 価値 |
|---|---|
| ターゲット プラットフォーム の | デスクトップ |
| ヘッダー | winddiui.h (Winddiui.h を含む) |