NotifyServiceStatusChangeW 関数 (winsvc.h)

指定したサービスが作成または削除されたとき、または状態が変更されたときに、アプリケーションが通知を受信できるようにします。

構文

DWORD NotifyServiceStatusChangeW(
  [in] SC_HANDLE        hService,
  [in] DWORD            dwNotifyMask,
  [in] PSERVICE_NOTIFYW pNotifyBuffer
);

パラメーター

[in] hService

サービスまたはサービス コントロール マネージャーへのハンドル。 サービスへのハンドルは OpenService 関数または CreateService 関数によって返され、SERVICE_QUERY_STATUSアクセス権が必要です。 サービス コントロール マネージャーへのハンドルは OpenSCManager 関数によって返され、SC_MANAGER_ENUMERATE_SERVICEアクセス権が必要です。 詳細については、「 サービス セキュリティとアクセス権」を参照してください。

サービスごとに未処理の通知要求は 1 つだけ存在できます。

[in] dwNotifyMask

報告する必要がある状態の変更の種類。 このパラメーターには、次の 1 つ以上の値を指定できます。

[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 が成功すると、通知 API はキューに登録されなくなります。 呼び出し元のスレッドがサービス ハンドルを閉じずに終了した場合、または APC が生成されるまで待機しないと、メモリ リークが発生する可能性があります。

要件

こちらもご覧ください

SERVICE_NOTIFY

SubscribeServiceChangeNotifications

サービス関数