DocumentProperties 関数

[アーティクル]
06/12/2023

DocumentProperties 関数は、プリンターの初期化情報を取得または変更するか、指定したプリンターのプリンター構成プロパティシートを表示します。

構文

LONG DocumentProperties(
  _In_  HWND     hWnd,
  _In_  HANDLE   hPrinter,
  _In_  LPTSTR   pDeviceName,
  _Out_ PDEVMODE pDevModeOutput,
  _In_  PDEVMODE pDevModeInput,
  _In_  DWORD    fMode
);

パラメーター

hWnd [in]

printer-configuration プロパティシートの親ウィンドウへのハンドル。

hPrinter [in]

プリンターオブジェクトへのハンドル。プリンターハンドルを取得するには 、OpenPrinter または AddPrinter 関数を使用します。

pDeviceName [in]

printer-configuration プロパティシートが表示されるデバイスの名前を指定する null で終わる文字列へのポインター。

pDevModeOutput [out]

ユーザーが指定したプリンター構成データを受け取る DEVMODE 構造体へのポインター。

pDevModeInput [in]

オペレーティングシステムがプロパティシートコントロールの初期化に使用する DEVMODE 構造体へのポインター。

このパラメーターは、fMode パラメーターで DM_IN_BUFFER フラグが設定されている場合にのみ使用されます。 DM_IN_BUFFERが設定されていない場合、オペレーティングシステムはプリンターの既定の DEVMODE を使用します。

fMode [in]

関数が実行する操作。このパラメーターが 0 の場合、 DocumentProperties 関数はプリンタードライバーの DEVMODE データ構造に必要なバイト数を返します。それ以外の場合は、次の定数の 1 つ以上を使用して、このパラメーターの値を作成します。ただし、印刷設定を変更するには、アプリケーションで少なくとも 1 つの入力値と 1 つの出力値を指定する必要があることに注意してください。

値	説明
DM_IN_BUFFER	入力値。プロンプト、コピー、または更新を行う前に、この関数は、プリンタードライバーの現在の印刷設定と、pDevModeInput パラメーターで指定された DEVMODE 構造体の設定をマージします。関数は、 DEVMODE 構造体の dmFields メンバーによって指定されたメンバーに対してのみ構造体を更新します。この値は、DM_MODIFYとしても定義されます。マージ中に競合が発生した場合、pDevModeInput によって指定された DEVMODE 構造体の設定は、プリンタードライバーの現在の印刷設定をオーバーライドします。
DM_IN_PROMPT	入力値。この関数は、プリンタードライバーの [印刷設定] プロパティシートを表示し、プリンターの DEVMODE データ構造の設定をユーザーが指定した値に変更します。この値は、DM_PROMPTとしても定義されます。
DM_OUT_BUFFER	出力値。関数は、プリンタードライバーの現在の印刷設定 (プライベートデータを含む) を、pDevModeOutput パラメーターで指定された DEVMODE データ構造に書き込みます。呼び出し元は、情報を格納するのに十分な大きさのバッファーを割り当てる必要があります。ビット DM_OUT_BUFFER セットが明確な場合は、pDevModeOutput パラメーターに NULL を指定できます。この値は、DM_COPYとしても定義されます。

戻り値

fMode パラメーターが 0 の場合、戻り値はプリンタードライバーの初期化データを格納するために必要なバッファーのサイズです。プリンタードライバーが構造体にプライベートデータを追加する場合、このバッファーは DEVMODE 構造体よりも大きくなる可能性があることに注意してください。

関数がプロパティシートを表示する場合、戻り値は、ユーザーが選択するボタンに応じて IDOK または IDCANCEL になります。

関数がプロパティシートを表示せず、成功した場合、戻り値は IDOK になります。

関数が失敗した場合、戻り値は 0 未満です。

注釈

注意

これはブロック関数または同期関数であり、すぐには返されない可能性があります。この関数が返す速度は、ネットワーク状態、プリントサーバーの構成、プリンタードライバーの実装要因など、アプリケーションの作成時に予測が困難な実行時の要因によって異なります。ユーザーインターフェイスとの対話を管理するスレッドからこの関数を呼び出すと、アプリケーションが応答しなくなる可能性があります。

pDeviceName パラメーターが指す文字列は、GetPrinter 関数を呼び出すことで取得できます。

プリンタードライバーによって実際に使用される DEVMODE 構造体には、デバイスに依存しない部分 (上記で定義) の後に、ドライバー固有の部分が含まれています。その後、ドライバーとドライバーのバージョンごとにサイズと内容が異なります。このドライバーに依存するため、アプリケーションでは、バッファーを割り当てる前に 、DEVMODE 構造体の正しいサイズのドライバーに対してクエリを実行することが非常に重要です。

アプリケーションに対してローカルな印刷設定を変更するには、アプリケーションで次の手順に従う必要があります。

DocumentProperties を呼び出し、fMode パラメーターに 0 を指定して、完全な DEVMODE 構造体に必要なバイト数を取得します。
完全な DEVMODE 構造体にメモリを割り当てます。
DocumentProperties を呼び出して、現在のプリンター設定を取得します。手順 2 で割り当てられた DEVMODE 構造体へのポインターを pDevModeOutput パラメーターとして渡し、 DM_OUT_BUFFER 値を指定します。
返された DEVMODE 構造体の適切なメンバーを変更し、DEVMODE の dmFields メンバーに対応するビットを設定して、どのメンバーが変更されたかを示します。
DocumentProperties を呼び出し、変更した DEVMODE 構造体を pDevModeInput パラメーターと pDevModeOutput パラメーターの両方として渡し、DM_IN_BUFFERとDM_OUT_BUFFERの両方の値 (OR 演算子を使用して組み合わされます) を指定します。DocumentProperties の 3 回目の呼び出しによって返される DEVMODE 構造体は、CreateDC 関数の呼び出しで引数として使用できます。

現在のプリンター設定を使用してプリンターとデバイスのコンテキストへのハンドルを作成するには、前述のように DocumentProperties を 2 回呼び出す必要があります。最初の呼び出しは完全な DEVMODE のサイズを取得し、2 番目の呼び出しでは、現在のプリンター設定を使用して DEVMODE を初期化します。初期化された DEVMODE を CreateDC に渡して、プリンターデバイスコンテキストへのハンドルを取得します。

要件

要件	値
サポートされている最小のクライアント	Windows 2000 Professional [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows 2000 Server [デスクトップアプリのみ]
ヘッダー	Winspool.h (Windows.h を含む)
ライブラリ	Winspool.lib
[DLL]	Winspool.drv
Unicode 名と ANSI 名	DocumentPropertiesW (Unicode) と DocumentPropertiesA (ANSI)

次の方法で共有

DocumentProperties 関数

構文

パラメーター

戻り値

注釈

要件

関連項目

フィードバック

その他のリソース