FindFirstPrinterChangeNotification 関数

  • [アーティクル]

FindFirstPrinterChangeNotification 関数は、変更通知オブジェクトを作成し、オブジェクトへのハンドルを返します。 その後、このハンドルを待機関数の 1 つを呼び出して、プリンターまたはプリント サーバーへの変更を監視できます。

FindFirstPrinterChangeNotification 呼び出しでは、監視する変更の種類を指定します。 変更を監視する一連の条件、監視するプリンター情報フィールドのセット、またはその両方を指定できます。

指定したプリンターまたはプリント サーバーで指定された変更のいずれかが発生すると、変更通知ハンドルに対する待機操作が成功します。 次に 、FindNextPrinterChangeNotification 関数を呼び出して変更に関する情報を取得し、次の待機操作で使用する変更通知オブジェクトをリセットします。

構文

HANDLE FindFirstPrinterChangeNotification(
  _In_     HANDLE hPrinter,
           DWORD  fdwFilter,
           DWORD  fdwOptions,
  _In_opt_ LPVOID pPrinterNotifyOptions
);

パラメーター

hPrinter [in]

監視するプリンターまたはプリント サーバーへのハンドル。 プリンター ハンドルを取得するには 、OpenPrinter または AddPrinter 関数を使用します。

fdwFilter

変更通知オブジェクトがシグナル状態になる条件。 変更通知は、指定された条件の 1 つ以上が満たされたときに発生します。 pPrinterNotifyOptions が NULL 以外の場合、fdwFilter パラメーターは 0 にすることができます。

このパラメーターには、次の 1 つ以上の値を指定できます。

値 説明
PRINTER_CHANGE_FORM
 フォームに対する変更を通知します。 この一般的なフラグまたは次の特定のフラグの 1 つ以上を設定できます。
PRINTER_CHANGE_ADD_FORM
PRINTER_CHANGE_SET_FORM
PRINTER_CHANGE_DELETE_FORM
PRINTER_CHANGE_JOB
 ジョブに対する変更を通知します。 この一般的なフラグまたは次の特定のフラグの 1 つ以上を設定できます。
PRINTER_CHANGE_ADD_JOB
PRINTER_CHANGE_SET_JOB
PRINTER_CHANGE_DELETE_JOB
PRINTER_CHANGE_WRITE_JOB
PRINTER_CHANGE_PORT
 ポートへの変更を通知します。 この一般的なフラグまたは次の特定のフラグの 1 つ以上を設定できます。
PRINTER_CHANGE_ADD_PORT
PRINTER_CHANGE_CONFIGURE_PORT
PRINTER_CHANGE_DELETE_PORT
PRINTER_CHANGE_PRINT_PROCESSOR
 印刷プロセッサに対する変更を通知します。 この一般的なフラグまたは次の特定のフラグの 1 つ以上を設定できます。
PRINTER_CHANGE_ADD_PRINT_PROCESSOR
PRINTER_CHANGE_DELETE_PRINT_PROCESSOR
PRINTER_CHANGE_PRINTER
 プリンターに対する変更を通知します。 この一般的なフラグまたは次の特定のフラグの 1 つ以上を設定できます。
PRINTER_CHANGE_ADD_PRINTER
PRINTER_CHANGE_SET_PRINTER
PRINTER_CHANGE_DELETE_PRINTER
PRINTER_CHANGE_FAILED_CONNECTION_PRINTER
PRINTER_CHANGE_PRINTER_DRIVER
 プリンター ドライバーに対する変更を通知します。 この一般的なフラグまたは次の特定のフラグの 1 つ以上を設定できます。
PRINTER_CHANGE_ADD_PRINTER_DRIVER
PRINTER_CHANGE_SET_PRINTER_DRIVER
PRINTER_CHANGE_DELETE_PRINTER_DRIVER
PRINTER_CHANGE_ALL
 上記の変更のいずれかが発生した場合に通知します。
PRINTER_CHANGE_SERVER
 Windows 7: サーバーへの変更を通知します。
このフラグは、 PRINTER_CHANGE_ALL 値を設定することによって監視される変更には含まれません。

前の表のより具体的なフラグの説明については、 FindNextPrinterChangeNotification 関数を参照してください。

fdwOptions

通知が機能するプリンターのカテゴリを決定するフラグ。

値 説明
PRINTER_NOTIFY_CATEGORY_ALL
0x001000
 FindNextPrinterChangeNotification は、2D プリンターと 3D プリンターの両方の通知を返します。
PRINTER_NOTIFY_CATEGORY_3D
0x002000
 FindNextPrinterChangeNotification は、3D プリンターに対してのみ通知を返します。

このフラグを 0 に設定すると、 FindFirstPrinterChangeNotification は 2D プリンターでのみ機能します。 これが既定値です。

pPrinterNotifyOptions [in, optional]

PRINTER_NOTIFY_OPTIONS構造体へのポインター。 この構造体の pTypes メンバーは、監視するプリンター情報フィールドを指定する 1 つ以上の PRINTER_NOTIFY_OPTIONS_TYPE 構造体の配列です。 変更通知は、指定されたフィールドの 1 つ以上が変更されたときに発生します。 変更が発生すると、 FindNextPrinterChangeNotification 関数は新しいプリンター情報を取得できます。 fdwFilter が 0 以外の場合、このパラメーターは NULL にすることができます。

監視できるフィールドの一覧については、「 PRINTER_NOTIFY_OPTIONS_TYPE」を参照してください。

戻り値

関数が成功した場合、戻り値は、指定されたプリンターまたはプリント サーバーに関連付けられている変更通知オブジェクトへのハンドルです。

失敗した場合の戻り値は、INVALID_HANDLE_VALUE です。

注釈

注意

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

プリンターまたはプリント サーバーを監視するには、 FindFirstPrinterChangeNotification 関数を呼び出し、返された変更通知オブジェクト ハンドルを いずれかの待機関数の呼び出しで使用します。 変更通知オブジェクトに対する待機操作は、変更通知オブジェクトがシグナル状態になったときに満たされます。 システムは、 fdwFilter または pPrinterNotifyOptions で指定された 1 つ以上の変更が監視対象のプリンターまたはプリント サーバーで発生したときに、オブジェクトに通知します。

FindFirstPrinterChangeNotification を呼び出すときは、fdwFilter を 0 以外にするか、pPrinterNotifyOptions を NULL 以外にする必要があります。 両方を指定すると、両方に対して通知が行われます。

プリンター変更通知オブジェクトの待機操作が満たされたら、 FindNextPrinterChangeNotification 関数を呼び出して、通知の原因を特定します。 fdwFilter で指定された条件の場合、FindNextPrinterChangeNotification は、変更された条件を報告します。 pPrinterNotifyOptions で指定されたプリンター情報フィールドの場合、FindNextPrinterChangeNotification は、変更されたフィールドと、これらのフィールドの新しい情報を報告します。 FindNextPrinterChangeNotification では、変更通知オブジェクトも非署名状態にリセットされるため、別の待機操作で使用してプリンターまたはプリント サーバーの監視を続行できます。

1 つの例外として、変更通知オブジェクトがシグナル状態でない場合は 、FindNextPrinterChangeNotification 関数を呼び出さないでください。 wait 関数がWAIT_TIMEOUT値を返す場合、変更オブジェクトはシグナル状態ではありません。 待機関数がタイムアウトせずに成功した場合にのみ、FindNextPrinterChangeNotification 関数を呼び出します。例外は、pPrinterNotifyOptions パラメーターに設定されたPRINTER_NOTIFY_OPTIONS_REFRESH ビットを使用して FindNextPrinterChangeNotification が呼び出されたときです。

変更通知オブジェクトが不要になったら、 FindClosePrinterChangeNotification 関数を呼び出して閉じます。

FindFirstPrinterChangeNotification の呼び出し元は、FindFirstPrinterChangeNotification に渡されるプリンター ハンドルが FindClosePrinterChangeNotification が呼び出されるまで有効なままであることを確認する必要があります。 プリンター変更通知ハンドルの前にプリンター ハンドルが閉じている場合、それ以降の通知は配信されません。

FindFirstPrinterChangeNotification は、3D プリンターの変更通知をサーバー ハンドルに送信しません。

注意

Service Pack 2 (SP2) 以降の Windows XP では、インターネット接続ファイアウォール (ICF) によってプリンター ポートが既定でブロックされますが、ファイルと印刷の共有の例外を有効にできます。 ユーザーが別のコンピューターにプリンター接続を行い、例外が有効になっていない場合、ユーザーはサーバーからプリンター変更通知を受け取りません。 マシン管理者は例外を有効にする必要があります。

要件

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

関連項目

印刷

印刷スプーラー API 関数

FindClosePrinterChangeNotification

FindNextPrinterChangeNotification

OpenPrinter

PRINTER_NOTIFY_OPTIONS

PRINTER_NOTIFY_OPTIONS_TYPE