DocumentProperties 関数

  • [アーティクル]

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 構造体の正しいサイズのドライバーに対してクエリを実行することが非常に重要です。

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

  1. DocumentProperties を呼び出し、fMode パラメーターに 0 を指定して、完全な DEVMODE 構造体に必要なバイト数を取得します。
  2. 完全な DEVMODE 構造体にメモリを割り当てます。
  3. DocumentProperties を呼び出して、現在のプリンター設定を取得します。 手順 2 で割り当てられた DEVMODE 構造体へのポインターを pDevModeOutput パラメーターとして渡し、 DM_OUT_BUFFER 値を指定します。
  4. 返された DEVMODE 構造体の適切なメンバーを変更し、DEVMODE の dmFields メンバーに対応するビットを設定して、どのメンバーが変更されたかを示します。
  5. 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)

関連項目

印刷

印刷スプーラー API 関数

AdvancedDocumentProperties

CreateDC

Devmode

GetPrinter

OpenPrinter