NotifyServiceStatusChangeA 関数 (winsvc.h)
指定したサービスが作成または削除されたとき、または状態が変更されたときに、アプリケーションが通知を受け取ることができます。
構文
DWORD NotifyServiceStatusChangeA(
[in] SC_HANDLE hService,
[in] DWORD dwNotifyMask,
[in] PSERVICE_NOTIFYA pNotifyBuffer
);
パラメーター
[in] hService
サービスまたはサービス コントロール マネージャーへのハンドル。 サービスへのハンドルは 、OpenService 関数または CreateService 関数によって返され、SERVICE_QUERY_STATUSアクセス権が必要です。 サービス コントロール マネージャーへのハンドルは OpenSCManager 関数によって返され、SC_MANAGER_ENUMERATE_SERVICEアクセス権が必要です。 詳細については、「 サービス セキュリティとアクセス権」を参照してください。
サービスごとに未処理の通知要求は 1 つだけ存在できます。
[in] dwNotifyMask
報告する必要がある状態の変更の種類。 このパラメーターには、次の 1 つ以上の値を指定できます。
| 値 | 意味 |
|---|---|
|
サービスが作成されたときに報告します。
hService パラメーターは、SCM へのハンドルである必要があります。 |
|
サービスが続行されようとしているときに報告します。
hService パラメーターは、サービスへのハンドルである必要があります。 |
|
アプリケーションが DeleteService 関数の呼び出しでサービスを指定した場合に報告します。 削除できるように、アプリケーションはサービスへのハンドルを閉じる必要があります。
hService パラメーターは、サービスへのハンドルである必要があります。 |
|
サービスが削除されたときに報告します。 アプリケーションがサービスへの開いているハンドルを持っている場合、この通知を受け取ることができません。
hService パラメーターは、SCM へのハンドルである必要があります。 |
|
サービスが一時停止中であることを報告します。
hService パラメーターは、サービスへのハンドルである必要があります。 |
|
サービスが一時停止したときに報告します。
hService パラメーターは、サービスへのハンドルである必要があります。 |
|
サービスの実行時にレポートを作成します。
hService パラメーターは、サービスへのハンドルである必要があります。 |
|
サービスの開始時にレポートを作成します。
hService パラメーターは、サービスへのハンドルである必要があります。 |
|
サービスが停止しているときに報告します。
hService パラメーターは、サービスへのハンドルである必要があります。 |
|
サービスが停止したことを報告します。
hService パラメーターは、サービスへのハンドルである必要があります。 |
[in] pNotifyBuffer
コールバック関数へのポインターなど、通知情報を含む SERVICE_NOTIFY構造体への ポインター。 コールバック関数が呼び出されるか、呼び出し元のスレッドが通知要求を取り消すまで、この構造体は有効なままである必要があります。
最初の呼び出しのコールバック関数がバッファーで終了するか、最初の通知要求が取り消されるまで、同じバッファー パラメーターを使用して NotifyServiceStatusChange を複数回呼び出さないでください。 それ以外の場合、コールバック関数が受け取るバッファーのバージョンは保証されません。
Windows Vista: コールバック関数のアドレスは、読み込まれたモジュールのアドレス範囲内にある必要があります。 したがって、コールバック関数は、実行時に生成されるコード (JIT コンパイラによって生成されたマネージド コードなど) や実行時に圧縮解除されるネイティブ コードにすることはできません。 この制限は、Windows Server 2008 および Windows Vista sp1 で削除されました。
戻り値
関数が成功した場合、戻り値は ERROR_SUCCESS です。 サービスが削除対象としてマークされている場合、戻り値はERROR_SERVICE_MARKED_FOR_DELETEされ、サービスへのハンドルを閉じる必要があります。 サービス通知がシステム状態より遅すぎる場合、関数は ERROR_SERVICE_NOTIFY_CLIENT_LAGGINGを返します。 この場合、クライアントは SCM へのハンドルを閉じ、新しいハンドルを開き、この関数をもう一度呼び出す必要があります。
関数が失敗した場合、戻り値は システム エラー コードの 1 つです。
注釈
NotifyServiceStatusChange 関数を使用すると、サービス アプリケーションに関する通知を受け取ることができます。 ドライバー サービスに関する通知を受信するために使用することはできません。
サービスの状態が変わると、システムは、指定されたコールバック関数を、呼び出し元のスレッドにキューに入れた非同期プロシージャ 呼び出し (APC) として呼び出します。 呼び出し元のスレッドは、通知を受け取るアラート可能な待機 ( SleepEx 関数を呼び出すなど) を入力する必要があります。 詳細については、「 非同期プロシージャ呼び出し」を参照してください。
NotifyServiceStatusChange が呼び出されたときにサービスが既に要求された状態にある場合、コールバック関数はすぐにキューに入れられます。 次に同じサービスと状態で関数を呼び出しても、サービスの状態が変更されていない場合、コールバック関数はすぐにキューに入れられます。コールバック関数は、次にサービスが要求された状態に入った時点でキューに入れられます。
NotifyServiceStatusChange 関数は、THREAD_SET_CONTEXTアクセス権を持つ呼び出し元スレッドで OpenThread 関数を呼び出します。 呼び出し元のスレッドにこのアクセス権がない場合、 NotifyServiceStatusChange は失敗します。 呼び出し元のスレッドが別のユーザーを偽装している場合は、コンテキストを設定するための十分なアクセス許可がない可能性があります。
待機を実行するスレッドから NotifyServiceStatusChange を呼び出す方が、追加のスレッドを作成するよりも効率的です。
コールバック関数が呼び出された後、呼び出し元は NotifyServiceStatusChange を呼び出して、追加の通知を受信する必要があります。 NotifyServiceStatusChange やその他の SCM 関数を含む Windows API の特定の関数では、リモート プロシージャ コール (RPC) を使用します。これらの関数は警告可能な待機操作を実行する可能性があるため、コールバック関数内からを呼び出しても安全ではありません。 代わりに、コールバック関数は通知パラメーターを保存し、コールバックの外部で追加の作業を実行する必要があります。
未処理の通知を取り消すには、 CloseServiceHandle 関数を使用してサービス ハンドルを閉じます。 CloseServiceHandle が成功すると、それ以上の通知 APCs はキューに入れなくなります。 呼び出し元のスレッドがサービス ハンドルを閉じずに終了するか、APC が生成されるまで待機しないと、メモリ リークが発生する可能性があります。
注意
winsvc.h ヘッダーは NotifyServiceStatusChange をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。
要件
| 要件 | 値 |
|---|---|
| サポートされている最小のクライアント | Windows Vista [デスクトップ アプリのみ] |
| サポートされている最小のサーバー | Windows Server 2008 [デスクトップ アプリのみ] |
| 対象プラットフォーム | Windows |
| ヘッダー | winsvc.h (Windows.h を含む) |
| Library | Advapi32.lib |
| [DLL] | Advapi32.dll |