OpenPrinter2 関数
プリンター オプションの一部を設定しながら、指定したプリンター、プリント サーバー、またはその他の種類の印刷サブシステム内のハンドルへのハンドルを取得します。
構文
BOOL OpenPrinter2(
_In_ LPCTSTR pPrinterName,
_Out_ LPHANDLE phPrinter,
_In_ LPPRINTER_DEFAULTS pDefault,
_In_ PPRINTER_OPTIONS pOptions
);
パラメーター
-
pPrinterName [in]
-
プリンターまたはプリント サーバー、プリンター オブジェクト、XcvMonitor、または XcvPort の名前を指定する、null で終わる定数文字列へのポインター。
プリンター オブジェクトの場合は、PrinterName,Job xxxx を使用します。 XcvMonitor の場合は、ServerName、XcvMonitor MonitorName を使用します。 XcvPort の場合は、ServerName、XcvPort PortName を使用します。
Windows Vista:NULL の場合は、ローカル印刷サーバーを示します。
-
phPrinter [out]
-
開いているプリンターまたはプリント サーバー オブジェクトへのハンドルを受け取る変数へのポインター。
-
pDefault [in]
-
PRINTER_DEFAULTS構造体へのポインター。 この値は NULL にすることができます。
-
pOptions [in]
-
PRINTER_OPTIONS構造体へのポインター。 この値は NULL にすることができます。
戻り値
関数が成功した場合、戻り値は 0 以外の値になります。
関数が失敗した場合は、0 を返します。 拡張エラー情報については、 GetLastError を呼び出します。
解説
DllMain では、このメソッドを呼び出さないでください。
Note
これはブロック関数または同期関数であり、すぐには返されない場合があります。 この関数が返す速度は、アプリケーションの作成時に予測が困難なネットワーク状態、プリント サーバーの構成、プリンター ドライバーの実装要因などの実行時の要因によって異なります。 ユーザー インターフェイスとの対話を管理するスレッドからこの関数を呼び出すと、アプリケーションが応答しなくなる可能性があります。
この関数の ANSI バージョンは実装されておらず、ERROR_NOT_SUPPORTEDを返します。
pDefault パラメーターを使用すると、StartDocPrinter 関数によって送信されたドキュメントの印刷に使用するデータ型とデバイス モードの値を指定できます。 ただし、これらの値は、ドキュメントの開始後に SetJob 関数を使用してオーバーライドできます。
OpenPrinter2 関数を呼び出して、プリント サーバーへのハンドルを開くか、プリント サーバーへのクライアント アクセス権を決定できます。 これを行うには、pPrinterName パラメーターでプリント サーバーの名前を指定し、PRINTER_DEFAULTS構造体の pDatatype メンバーと pDevMode メンバーを NULL に設定し、DesiredAccess メンバーを設定して、SERVER_ALL_ACCESSなどのサーバー アクセス マスク値を指定します。 ハンドルが完成したら、 ClosePrinter 関数に渡して閉じます。
PRINTER_DEFAULTS構造体の DesiredAccess メンバーを使用して、必要なアクセス権を指定します。 アクセス権には、次のいずれかを指定できます。
| 必要なアクセス値 | 説明 |
|---|---|
| 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」を参照してください。 |
ユーザーが目的のアクセス権を持つ指定したプリンターまたはプリント サーバーを開く権限がない場合、 OpenPrinter2 呼び出しは失敗し、 GetLastError は値ERROR_ACCESS_DENIEDを返します。
pPrinterName がローカル プリンターの場合、OpenPrinter2 は、PRINTER_OPTIONS構造体が pOptions を使用して指していた dwFlags のすべての値を無視します (PRINTER_OPTION_CLIENT_CHANGEを除く)。 後者が渡された場合、 OpenPrinter2 はERROR_ACCESS_DENIEDを返します。 したがって、ローカル プリンターを開くと、 OpenPrinter2 は OpenPrinter よりも利点がありません。
Windows Vista:OpenPrinter2 によって返されるプリンター データは、pOptions によって参照されるPRINTER_OPTIONS構造体の dwFlags フィールドに PRINTER_OPTION_NO_CACHE フラグが設定されていない限り、ローカル キャッシュから取得されます。
例
この例では、PRINTER_ACCESS_MANAGE_LIMITEDがPRINTER_DEFAULTS構造体に渡され、ユーザーに適切なアクセス許可がない場合、OpenPrinter2 は失敗します。
// Specify the limited management permission.
PRINTER_DEFAULTS defaults = {};
defaults.DesiredAccess = PRINTER_ACCESS_MANAGE_LIMITED;
// Open a printer to which the user has no administrative rights.
HANDLE printer = nullptr;
assert(!OpenPrinter2(L QueueWithNoAdminRights , // Queue name
&printer, // Printer handle
&defaults, // Printer defaults
nullptr)); // Printer options
assert(GetLastError() == ERROR_ACCESS_DENIED);
if (printer)
{
ClosePrinter(printer);
}
この関数の使用方法を示すサンプル プログラムについては、「 方法: GDI Print API を使用して印刷する」を参照してください。
必要条件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント |
Windows Vista [デスクトップ アプリのみ] |
| サポートされている最小のサーバー |
Windows Server 2008 [デスクトップ アプリのみ] |
| Header |
|
| ライブラリ |
|
| [DLL] |
|
| Unicode 名と ANSI 名 |
OpenPrinter2W (Unicode) と OpenPrinter2A (ANSI) |