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 に設定されている場合、これは 0 です。 64 ビット バージョンのWindowsでの 32 ビット アプリケーションからの印刷に関する制限については、「解説」を参照してください。
-
iEsc
-
処理するイベントを識別するエスケープ コード。 このパラメーターには、次のいずれかの整数定数を指定できます。
常時 イベント - DOCUMENTEVENT_ABORTDOC
GDI では、 AbortDoc 関数の呼び出しを処理します。 - DOCUMENTEVENT_CREATEDCPOST
GDI は、 CreateDC または CreateIC 関数の呼び出しを処理したばかりです。
iEsc を DOCUMENTEVENT_CREATEDCPRE に設定して DocumentEvent を以前に呼び出していない限り、このエスケープ コードを使用しないでください。- 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 関数の呼び出しを処理したばかりです。
このエスケープ コードは、iEsc を DOCUMENTEVENT_RESETDCPRE に設定した DocumentEvent の以前の呼び出しがない限り使用しないでください。- 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 は 、 StartDoc によって返される印刷ジョブ ID を指定する LONG を指します。 - 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 構造体へのポインター。この構造体は、 CreateDC 呼び出し元によって提供される構造体の代わりに GDI によって使用されます。 ( NULL の場合、GDI は呼び出し元が指定した構造体を使用します)。 - DOCUMENTEVENT_ESCAPE
ExtEscape の lpszOutData パラメーターとして使用されるバッファーへのポインター。 - DOCUMENTEVENT_QUERYFILTER
Windows ドライバー開発キットに記載されているDOCEVENT_FILTER構造体を含むバッファーへのポインター。 - DOCUMENTEVENT_RESETDCPRE
ドライバーが提供する DEVMODE 構造体へのポインター。この構造体は、 ResetDC 呼び出し元によって提供される構造体の代わりに GDI によって使用されます。 ( 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の戻り値を提供します。 |
注釈
DOCUMENTEVENT_QUERYFILTERの iEsc 値の場合、スプーラーは、ドライバーがDOCEVENT_FILTER構造体の特定のメンバー (Windows ドライバー開発キットに記載されている) を変更したかどうかに応じて、DocumentEvent によって返されるDOCUMENTEVENT_SUCCESS値を 2 つの方法で解釈できます。 ( pvOut パラメーターは、この構造体を指します。スプーラーは、この型の構造体にメモリを割り当てると、この構造体の 2 つのメンバー ( cElementsReturned と cElementsNeeded) を既知の値に初期化します。 DocumentEvent が戻った後、スプーラーはこれらのメンバーの値が変更されたかどうかを判断し、その情報を使用して DocumentEvent の戻り値を解釈します。 次の表は、この状況をまとめたものです。
| 戻り値 | cElementsReturned および cElementsNeededed の状態 | 意味 |
|---|---|---|
| DOCUMENTEVENT_SUCCESS |
ドライバーは、どちらのメンバーにも変更を加えなくなりました。 |
スプーラーは、この戻り値をDOCUMENTEVENT_UNSUPPORTEDと同等と解釈します。 スプーラーはドライバーからイベント フィルターを取得できないため、すべてのイベントに対して DocumentEvent を呼び出しても保持されます。 |
| DOCUMENTEVENT_SUCCESS |
ドライバーは、一方または両方のメンバーに書き込んだ。 |
スプーラーはこの戻り値を解釈せずに受け入れます。 ドライバーが cElementsNeeded と cElementsReturned の 1 つだけに書き込 んだ場合、スプーラーは変更されていないメンバーの値が 0 であると見なします。 スプーラーは、DOCEVENT_FILTERの aDocEventCall メンバーに一覧表示されているすべてのイベントをフィルター処理します (Windows ドライバー開発キットに記載されています)。 |
| DOCUMENTEVENT_UNSUPPORTED |
適用なし |
ドライバーはDOCUMENTEVENT_QUERYFILTERをサポートしていません。 スプーラーはドライバーからイベント フィルターを取得できないため、すべてのイベントに対して DocumentEvent を呼び出しても保持されます。 |
| DOCUMENTEVENT_FAILURE |
適用なし |
ドライバーはDOCUMENTEVENT_QUERYFILTERをサポートしていますが、内部エラーが発生しました。 スプーラーはドライバーからイベント フィルターを取得できないため、すべてのイベントに対して DocumentEvent を呼び出しても保持されます。 |
iEsc パラメーターで指定されたエスケープ コードがDOCUMENTEVENT_CREATEDCPRE場合は、次の規則が適用されます。
- ジョブがスプールなしでプリンターに直接送信されている場合、pvIn-pszDevice> はプリンター名を指します。 (詳細については、Windows ドライバー開発キットのDOCEVENT_CREATEDCPRE構造のドキュメントを参照してください)。
- ジョブがスプールされている場合、pvIn-pszDevice> はプリンター・ポート名を指します。
Note
64 ビット バージョンのWindowsで 32 ビット アプリケーションを実行する場合は、次の制限が適用されます。 DocumentEvent で呼び出す必要がある GDI 関数は ExtEscape のみで、プライベート エスケープのみを使用する必要があります。 他の GDI 関数に対する DocumentEvent 呼び出しでは、未定義の動作が発生する可能性があります。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント |
Windows Vista [デスクトップ アプリのみ] |
| サポートされている最小のサーバー |
Windows Server 2008 [デスクトップ アプリのみ] |
| Header |
|
| Unicode 名と ANSI 名 |
DocumentEventW (Unicode) と DocumentEventA (ANSI) |