SetPrinter 関数
SetPrinter 関数は、印刷の一時停止、印刷の再開、またはすべての印刷ジョブのクリアによって、指定したプリンターのデータを設定するか、指定したプリンターの状態を設定します。
構文
BOOL SetPrinter(
_In_ HANDLE hPrinter,
_In_ DWORD Level,
_In_ LPBYTE pPrinter,
_In_ DWORD Command
);
パラメーター
-
hPrinter [in]
-
プリンターのハンドル。 プリンター ハンドルを取得するには、 OpenPrinter、 OpenPrinter2、または AddPrinter 関数を使用します。
-
レベル [入力]
-
pPrinter が指すバッファーに関数が格納するデータの型。 Command パラメーターが 0 に等しくない場合、Level パラメーターは 0 である必要があります。
この値には、0、2、3、4、5、6、7、8、または 9 を指定できます。
-
pPrinter [in]
-
プリンター用に設定するデータを含むバッファー、または Command パラメーターで指定されたコマンドの情報を含むバッファーへのポインター。 バッファー内のデータの種類は、 Level の値によって決まります。
Level 構造体 - 0
Command パラメーターがPRINTER_CONTROL_SET_STATUS場合、pPrinter には、設定する新しいプリンターの状態を指定する DWORD 値が含まれている必要があります。 使用可能な状態値の一覧については、PRINTER_INFO_2構造体の Status メンバーを参照してください。 PRINTER_STATUS_PAUSEDとPRINTER_STATUS_PENDING_DELETIONは、設定する有効な状態値ではないことに注意してください。
Level が 0 で Command パラメーターがPRINTER_CONTROL_SET_STATUSされていない場合、pPrinter は NULL である必要があります。- 2
プリンター に 関する詳細情報を含むPRINTER_INFO_2構造体。 - 3
プリンターのセキュリティ情報を含む PRINTER_INFO_3 構造体。 - 4
プリンターの名前、サーバーの名前、プリンターがリモートかローカルかを含む、最小限のプリンター情報を含むPRINTER_INFO_4構造体。 - 5
プリンター属性やタイムアウト設定などのプリンター情報を含む PRINTER_INFO_5 構造体。 - 6
プリンターの状態値を指定する PRINTER_INFO_6 構造体。 - 7
PRINTER_INFO_7構造体。 この構造体の dwAction メンバーは、 SetPrinter がディレクトリ サービス内のプリンターのデータを発行、発行解除、再発行、または更新する必要があるかどうかを示します。 - 8
グローバルな既定のプリンター設定を指定する PRINTER_INFO_8 構造体。 - 9
ユーザーごとの既定のプリンター設定を指定する PRINTER_INFO_9 構造体。 -
コマンド [入力]
-
実行するアクション。
Level パラメーターが 0 以外の場合は、このパラメーターの値を 0 に設定します。 この場合、プリンターは現在の状態を保持し、関数は Level パラメーターと pPrinter パラメーターで指定されたプリンター データを再構成します。
Level パラメーターが 0 の場合は、このパラメーターの値を次のいずれかの値に設定します。
値 説明 - PRINTER_CONTROL_PAUSE
プリンターを一時停止します。 - PRINTER_CONTROL_PURGE
プリンター内のすべての印刷ジョブを削除します。 - PRINTER_CONTROL_RESUME
一時停止しているプリンターを再開します。 - PRINTER_CONTROL_SET_STATUS
プリンターの状態を設定します。
pPrinter パラメーターを、新しいプリンターの状態を指定する DWORD 値へのポインターに設定します。
戻り値
関数が成功した場合、戻り値は 0 以外の値になります。
関数が失敗した場合は、0 を返します。
Level が 7 で発行アクションが失敗した場合、SetPrinter はERROR_IO_PENDINGを返し、バックグラウンドでアクションの完了を試みます。 Level が 7 で、更新アクションが失敗した場合、SetPrinter はERROR_FILE_NOT_FOUNDを返します。
注釈
注意
これはブロック関数または同期関数であり、すぐには返されない可能性があります。 この関数が返す速度は、ネットワーク状態、プリント サーバーの構成、プリンター ドライバーの実装要因など、アプリケーションの作成時に予測が困難な実行時の要因によって異なります。 ユーザー インターフェイスとの対話を管理するスレッドからこの関数を呼び出すと、アプリケーションが応答しなくなる可能性があります。
SetPrinter を使用して既定のプリンターを変更することはできません。
現在のプリンター設定を変更するには、 GetPrinter 関数を呼び出して現在の設定を PRINTER_INFO_2 構造体に取得し、必要に応じてその構造体のメンバーを変更してから 、SetPrinter を呼び出します。
SetPrinter 関数は、PRINTER_INFO_2構造体の pServerName、AveragePPM、Status、および cJobs メンバーを無視します。
プリンターを一時停止すると、現在印刷されている可能性がある 1 つの印刷ジョブを除き、そのプリンターのすべての印刷ジョブのスケジュールが一時停止されます。 印刷ジョブは一時停止しているプリンターに送信できますが、印刷が再開されるまで、そのプリンターでの印刷はスケジュールされません。 プリンターをクリアすると、現在の印刷ジョブを除き、そのプリンターのすべての印刷ジョブが削除されます。
SetPrinter を使用してプリンターの既定の DEVMODE 構造体を変更する (プリンターの既定値をグローバルに設定する) 場合は、まず DocumentProperties 関数を呼び出して DEVMODE 構造体を検証する必要があります。
セキュリティ記述子へのポインターを含む PRINTER_INFO_2 構造体と PRINTER_INFO_3 構造体の場合、関数は、呼び出し元が変更するアクセス許可を持つセキュリティ記述子のコンポーネントのみを設定できます。 特定のセキュリティ記述子コンポーネントを設定するには、OpenPrinter 関数または OpenPrinter2 関数を呼び出してプリンターへのハンドルを取得するときに必要なアクセス権を指定する必要があります。 次の表は、さまざまなセキュリティ記述子コンポーネントを変更するために必要なアクセス権を示しています。
| アクセス許可 | セキュリティ記述子コンポーネント |
|---|---|
| WRITE_OWNER | 所有者 プライマリ グループ |
| WRITE_DAC | 随意アクセス制御リスト (DACL) |
| ACCESS_SYSTEM_SECURITY | システム アクセス制御リスト (SACL) |
セキュリティ記述子に、呼び出し元が変更するアクセス権を持たないコンポーネントが含まれている場合、 SetPrinter は失敗します。 変更しないセキュリティ記述子のコンポーネントは、必要に応じて NULL または存在しない必要があります。 セキュリティ記述子を変更せず、PRINTER_INFO_2構造体で SetPrinter を呼び出す場合は、その構造体の pSecurityDescriptor メンバーを NULL に設定します。
インターネット接続ファイアウォール (ICF) は既定でプリンター ポートをブロックしますが、ファイルと印刷の共有の例外を有効にすることができます。 SetPrinter がマシン管理者によって呼び出されると、例外が有効になります。 管理者以外によって呼び出され、例外がまだ有効になっていない場合、呼び出しは失敗します。
PRINTER_INFO_7構造でレベル 7 を使用して、プリンターのディレクトリ サービス データを発行、発行解除、または更新できます。 プリンターのディレクトリ サービス データには、プリンターの SetPrinterDataEx 関数の呼び出しによって、SPLDS_* キーの下に格納されているすべてのデータが含まれます。 SetPrinter を呼び出す前に、PRINTER_INFO_7 の pszObjectGUID メンバーを NULL に設定し、dwAction メンバーを次のいずれかの値に設定します。
| 値 | 説明 |
|---|---|
|
DSPRINT_PUBLISH |
ディレクトリ サービス データを発行します。 |
|
DSPRINT_REPUBLISH |
プリンターのディレクトリ サービス データは発行解除され、発行されたプリンター内のすべてのプロパティが更新されて、もう一度発行されます。 再発行では、発行されたプリンターの GUID も変更されます。 プリンターのパブリッシュされたデータが破損していると思われる場合は、この値を使用します。 |
|
DSPRINT_UNPUBLISH |
ディレクトリ サービス データの発行を取り消します。 |
|
DSPRINT_UPDATE |
ディレクトリ サービス データを更新します。 これは DSPRINT_PUBLISHと同じですが、プリンターがまだ発行されていない場合、 SetPrinter は ERROR_FILE_NOT_FOUND で失敗します。 DSPRINT_UPDATEを使用して発行済みプロパティを更新しますが、発行を強制することはできません。 プリンター ドライバーでは、DSPRINT_PUBLISHではなく、常 にDSPRINT_UPDATE を使用 する必要があります。 |
DSPRINT_PENDINGは SetPrinter の有効な dwAction 値ではありません。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント |
Windows 2000 Professional [デスクトップ アプリのみ] |
| サポートされている最小のサーバー |
Windows 2000 Server [デスクトップ アプリのみ] |
| ヘッダー |
|
| ライブラリ |
|
| [DLL] |
|
| Unicode 名と ANSI 名 |
SetPrinterW (Unicode) と SetPrinterA (ANSI) |