OpenPrinter 関数

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

OpenPrinter 関数は、指定されたプリンターまたはプリントサーバー、または印刷サブシステム内の他の種類のハンドルへのハンドルを取得します。

構文

BOOL OpenPrinter(
  _In_  LPTSTR             pPrinterName,
  _Out_ LPHANDLE           phPrinter,
  _In_  LPPRINTER_DEFAULTS pDefault
);

パラメーター

pPrinterName [in]

プリンターまたはプリントサーバー、プリンターオブジェクト、XcvMonitor、または XcvPort の名前を指定する null で終わる文字列へのポインター。

プリンターオブジェクトの場合は、PrinterName、ジョブ xxxx を使用します。 XcvMonitor の場合は、ServerName、XcvMonitor MonitorName を使用します。 XcvPort の場合は、ServerName、XcvPort PortName を使用します。

NULL の場合は、ローカルプリンターサーバーを示します。

phPrinter [out]

開いているプリンターまたはプリントサーバーオブジェクトへのハンドル (スレッドセーフではない) を受け取る変数へのポインター。

phPrinter パラメーターは、XcvData 関数で使用するために Xcv ハンドルを返すことができます。 XcvData の詳細については、DDK に関するページを参照してください。

pDefault [in]

PRINTER_DEFAULTS構造体へのポインター。この値は NULL にすることができます。

戻り値

関数が成功した場合、戻り値は 0 以外の値になります。

関数が失敗した場合は、0 を返します。

注釈

DllMain では、このメソッドを呼び出さないでください。

注意

リモートプリンターの OpenPrinter の呼び出しによってリモートプリンター用に取得されたハンドルは、印刷スプーラーサービスのローカルキャッシュを介してプリンターにアクセスします。このキャッシュはリアルタイムでは正確ではありません。正確なデータを取得するには、OpenPrinter 呼び出しを OpenPrinter2 に置き換え、pOptions.dwFlags を PRINTER_OPTION_NO_CACHE に設定します。 OpenPrinter2W のみが機能します。関数は、他の Printing API 呼び出しを使用し、ローカルキャッシュをバイパスするプリンターハンドルを返します。このメソッドは、リモートプリンターとのネットワーク通信を待機している間にブロックされるため、すぐには返されない可能性があります。この関数が返す速度は、アプリケーションの作成時に予測が困難なネットワーク状態、プリントサーバーの構成、プリンタードライバーの実装要因などの実行時の要因によって異なります。ユーザーインターフェイスの対話を管理するスレッドからこの関数を呼び出すと、アプリケーションが応答しなくなる可能性があります。

注意

リモートプリンターの OpenPrinter の呼び出しによって取得されたハンドルは、印刷スプーラーサービスのローカルキャッシュを介してプリンターにアクセスします。このキャッシュは、設計上、リアルタイムでは正確ではありません。正確なデータを取得する必要がある場合は、 OpenPrinter 呼び出しを OpenPrinter2 に置き換え、 pOptions.dwFlags を PRINTER_OPTION_NO_CACHE に設定します。 OpenPrinter2W のみが機能します。そうすることで、関数は、ローカルキャッシュをバイパスするために他の印刷 API 呼び出しを行うプリンターハンドルを返します。この方法では、リモートプリンターへのラウンドトリップネットワーク通信を待機している間にブロックされるため、すぐには戻らない場合があることに注意してください。この関数が返す速度は、ネットワーク状態、プリントサーバーの構成、プリンタードライバーの実装などの実行時の要因によって異なります。アプリケーションの作成時に予測が困難な要因です。したがって、ユーザーインターフェイスとの対話を管理するスレッドからこの関数を呼び出すと、アプリケーションが応答しなくなる可能性があります。

phPrinter が指すハンドルはスレッドセーフではありません。呼び出し元が複数のスレッドで同時に使用する必要がある場合は、同期関数を使用してプリンターハンドルへのカスタム同期アクセスを提供する必要があります。カスタムコードを記述しないようにするために、アプリケーションは必要に応じて各スレッドでプリンターハンドルを開くことができます。

pDefault パラメーターを使用すると、StartDocPrinter 関数によって送信されたドキュメントの印刷に使用するデータ型とデバイスモードの値を指定できます。ただし、これらの値は、ドキュメントの開始後に SetJob 関数を使用してオーバーライドできます。

startDocPrinter 呼び出しの pDocInfo パラメーターで渡されたDOC_INFO_1構造体の pDatatype メンバーの値が "RAW" の場合、pDefault パラメーターのPRINTER_DEFAULTS構造体で定義されている DEVMODE 設定は使用されません。高度なドキュメント (Adobe PDF や Microsoft Word ファイルなど) またはその他のプリンターデータ (PCL、PS、HPGL など) が、pDatatype が "RAW" に設定されたプリンターに直接送信される場合、ドキュメントでは、ハードウェアによって認識される言語で DEVMODE スタイルの印刷ジョブ設定を完全に記述する必要があります。

OpenPrinter 関数を呼び出して、プリントサーバーへのハンドルを開くか、クライアントがプリントサーバーに対して持っているアクセス権を決定できます。これを行うには、pPrinterName パラメーターで印刷サーバーの名前を指定し、PRINTER_DEFAULTS構造体の pDatatype メンバーと pDevMode メンバーを NULL に設定し、DesiredAccess メンバーを設定して、SERVER_ALL_ACCESSなどのサーバーアクセスマスク値を指定します。ハンドルを使用して終了したら、 ClosePrinter 関数に渡して閉じます。

プリンターに必要なアクセス権を指定するには、PRINTER_DEFAULTS構造体の DesiredAccess メンバーを使用します。アクセス権には、次のいずれかを指定できます。 ( pDefault が NULL の場合、アクセス権はPRINTER_ACCESS_USE。

必要なアクセス値	説明
PRINTER_ACCESS_ADMINISTER	SetPrinter によって提供される管理タスクなど、管理タスクを実行します。
PRINTER_ACCESS_USE	基本的な印刷操作を実行します。
PRINTER_ALL_ACCESS	SYNCHRONIZE を除くすべての管理タスクと基本的な印刷操作を実行するには ( 「Standard Access Rights」を参照してください。
PRINTER_ACCESS_MANAGE_LIMITED	SetPrinter や SetPrinterData によって提供される管理タスクを実行します。この値は、Windows 8.1 以降で使用できます。
WRITE_DACなどの汎用セキュリティ値	特定の制御アクセス権を許可する。「Standard Access Rights」を参照してください。

ユーザーが目的のアクセス権を持つ指定したプリンターまたはプリントサーバーを開く権限がない場合、 OpenPrinter 呼び出しは 0 の戻り値で失敗し、 GetLastError は値ERROR_ACCESS_DENIEDを返します。

例

この関数を使用するサンプルプログラムについては、「方法: GDI Print API を使用して印刷する」を参照してください。

要件

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

OpenPrinter 関数

構文

パラメーター

戻り値

注釈

例

要件

関連項目

フィードバック

フィードバック

その他のリソース