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

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

定数	Event
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 Contents
DOCUMENTEVENT_ABORTDOC	使用しません。
DOCUMENTEVENT_CREATEDCPOST	pvIn には、iEsc パラメーターが DOCUMENTEVENT_CREATEDCPRE に設定された、この関数の以前の呼び出しで pvOut パラメーターで指定された DEVMODE 構造体へのポインターのアドレスが含まれています。
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 には、iEsc パラメーターが DOCUMENTEVENT_RESETDCPRE に設定された、この関数の以前の呼び出しで pvOut パラメーターで指定された DEVMODE 構造体へのポインターのアドレスが含まれています。
DOCUMENTEVENT_RESETDCPRE	pvIn には、ResetDC の呼び出し元によって提供される DEVMODE 構造体へのポインターのアドレスが含まれています。
DOCUMENTEVENT_STARTDOCPOST	pvIn は、StartDoc によって返される印刷ジョブ識別子を指定する LONG を指します。
DOCUMENTEVENT_STARTDOCPRE または DOCUMENTEVENT_STARTDOC	pvIn には、StartDoc の呼び出し元によって提供される DOCINFO 構造体へのポインターのアドレスが含まれています。
DOCUMENTEVENT_STARTPAGE	使用しません。

cbOut

Value	意味
IDOCUMENTEVENT_QUERYFILTER	pvOut によるバッファー ポインターのサイズ (バイト単位)。
DOCUMENTEVENT_ESCAPE	ExtEscape の cbOutput パラメーターとして使用される値。
その他すべての値	iEsc は使用されません。

pvOut [out]

バッファーへのポインター。 次の表に示すように、バッファーの内容は、iEsc に指定される値によって異なります。

定数	pvOut コンテンツ
DOCUMENTEVENT_CREATEDCPRE	ドライバーが提供する DEVMODE 構造体へのポインター。GDI は、CreateDC 呼び出し元によって提供される構造体の代わりに使用されます。 (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 値の場合、スプーラーは、ドライバーが (Windows ドライバー開発キットに記載されている) DOCEVENT_FILTER 構造体の特定のメンバーを変更したかどうかに応じて、DocumentEvent によって返される DOCUMENTEVENT_SUCCESS 値を 2 つの方法で解釈できます。 (pvOut パラメーターは、この構造体を指します。)スプーラーは、この型の構造体にメモリを割り当てるときに、この構造体の 2 つのメンバー (cElementsReturned と cElementsNeeded)を既知の値に初期化します。 DocumentEvent が戻った後、スプーラーはこれらのメンバーの値が変更されたかどうかを判断し、その情報を使用して DocumentEvent の戻り値を解釈します。 次の表に、この状況をまとめます。

戻り値	cElementsReturned と cElementsNeeded の状態	意味
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 呼び出しでは、未定義の動作が発生する可能性があります。

要件

要件	Value
サポートされている最小のクライアント	Windows Vista [デスクトップ アプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップ アプリのみ]
ヘッダー	Winspool.h (include Windows.h)
Unicode 名と ANSI 名	DocumentEventW (Unicode) と DocumentEventA (ANSI)

関連項目

• 印刷
• 印刷スプーラー API 関数
• Windows ドライバー開発キット