NotifyServiceStatusChangeW

指定したサービスが作成または削除されたとき、またはその状態が変化したときにアプリケーションが通知を受け取れるようにする。(Unicode)

NotifyServiceStatusChangeW hService, dwNotifyMask, pNotifyBuffer

hService : [intptr] サービスまたはサービスコントロールマネージャへのハンドル。サービスへのハンドルは OpenService または CreateService 関数によって返され、SERVICE_QUERY_STATUS アクセス権を持つ必要がある。サービスコントロールマネージャへのハンドルは OpenSCManager 関数によって返され、SC_MANAGER_ENUMERATE_SERVICE アクセス権を持つ必要がある。詳細は「Service Security and Access Rights」を参照。サービスごとに未処理の通知要求は 1 つだけ存在できる。
dwNotifyMask : [int] 
pNotifyBuffer : [var] コールバック関数へのポインタなどの通知情報を含む SERVICE_NOTIFY 構造体へのポインタ。この構造体は、コールバック関数が呼び出されるか、呼び出し元スレッドが通知要求を取り消すまで有効でなければならない。最初の呼び出しのコールバック関数がバッファの使用を終えるか、最初の通知要求が取り消されるまで、同じバッファパラメータで NotifyServiceStatusChange を複数回呼び出してはならない。そうしないと、コールバック関数がどのバージョンのバッファを受け取るかが保証されない。Windows Vista: コールバック関数のアドレスはロードされたモジュールのアドレス範囲内になければならない。したがって、コールバック関数は実行時に生成されたコード (JIT コンパイラによって生成されたマネージコードなど) や実行時に展開されるネイティブコードであってはならない。この制限は Windows Server 2008 および Windows Vista SP1 で削除された。

(プラグイン / モジュール : advapi32.dll)

解説

指定したサービスが作成または削除されたとき、またはその状態が変化したときにアプリケーションが通知を受け取れるようにする。(Unicode)

[戻り値]
関数が成功した場合、戻り値は ERROR_SUCCESS である。サービスが削除対象としてマークされている場合、戻り値は
ERROR_SERVICE_MARKED_FOR_DELETE
であり、サービスへのハンドルを閉じる必要がある。サービス通知がシステム状態から大きく遅れている場合、関数は
ERROR_SERVICE_NOTIFY_CLIENT_LAGGING を返す。この場合、クライアントは SCM
へのハンドルを閉じ、新しいハンドルを開いてこの関数を再度呼び出す必要がある。関数が失敗した場合、戻り値はシステムエラーコードのいずれかである。

[備考]
NotifyServiceStatusChange
関数は、サービスアプリケーションに関する通知を受け取るために使用できる。ドライバサービスに関する通知を受け取るためには使用できない。サービス状態が変更されると、システムは呼び出し元スレッドにキューイングされた非同期プロシージャ呼び出し
(APC) として指定されたコールバック関数を呼び出す。通知を受け取るには、呼び出し元スレッドはアラート可能待機に入る必要がある (例えば
SleepEx 関数を呼び出す)。詳細は「Asynchronous Procedure
Calls」を参照。NotifyServiceStatusChange
が呼び出されたときにサービスが既に要求された状態のいずれかにある場合、コールバック関数は即座にキューイングされる。同じサービスと状態で関数が次に呼び出されるまでにサービス状態が変化していない場合、コールバック関数は即座にキューイングされない。コールバック関数はサービスが次に要求された状態に入ったときにキューイングされる。
> [!NOTE] > winsvc.h ヘッダーは NotifyServiceStatusChange
をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI 版または Unicode
版を自動的に選択する。詳細は [Conventions for Function
Prototypes](/windows/win32/intl/conventions-for-function-prototypes)
を参照。

情報