次の方法で共有


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 ExtEscapecbOutput パラメーターとして使用される値。
その他すべての値 iEsc は使用されません。

pvOut [out]

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

定数 pvOut コンテンツ
DOCUMENTEVENT_CREATEDCPRE
ドライバーが提供する DEVMODE 構造体へのポインター。GDI は、CreateDC 呼び出し元によって提供される構造体の代わりに使用されます。 (NULL の場合、GDI は呼び出し元により指定される構造体を使用します)。
DOCUMENTEVENT_ESCAPE
ExtEscapelpszOutData パラメーターとして使用されるバッファーへのポインター。
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 つのメンバー (cElementsReturnedcElementsNeeded)を既知の値に初期化します。 DocumentEvent が戻った後、スプーラーはこれらのメンバーの値が変更されたかどうかを判断し、その情報を使用して DocumentEvent の戻り値を解釈します。 次の表に、この状況をまとめます。

戻り値 cElementsReturned と cElementsNeeded の状態 意味
DOCUMENTEVENT_SUCCESS
ドライバーにより、どちらのメンバーにも変更は加えられていません。
スプーラーは、この戻り値を DOCUMENTEVENT_UNSUPPORTED と同等と解釈します。 スプーラーはドライバーからイベント フィルターを取得できないため、すべてのイベントに対して DocumentEvent を呼び出し続けます。
DOCUMENTEVENT_SUCCESS
ドライバーが一方または両方のメンバーに書き込みました。
スプーラーは、解釈せずにこの戻り値を受け入れます。 ドライバーが cElementsNeededcElementsReturned のうち 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)

関連項目