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 つ以上の値を指定できます。

意味
SERVICE_NOTIFY_CREATED
0x00000080
サービスが作成されたときに報告します。

hService パラメーターは、SCM へのハンドルである必要があります。

SERVICE_NOTIFY_CONTINUE_PENDING
0x00000010
サービスが続行しようとしているときに報告します。

hService パラメーターは、サービスへのハンドルである必要があります。

SERVICE_NOTIFY_DELETE_PENDING
0x00000200
アプリケーションが DeleteService 関数の呼び出しでサービスを指定した場合に報告します。 削除できるように、アプリケーションはサービスへのハンドルを閉じる必要があります。

hService パラメーターは、サービスへのハンドルである必要があります。

SERVICE_NOTIFY_DELETED
0x00000100
サービスが削除されたときに報告します。 サービスへの開いているハンドルがある場合、アプリケーションはこの通知を受け取ることができません。

hService パラメーターは、SCM へのハンドルである必要があります。

SERVICE_NOTIFY_PAUSE_PENDING
0x00000020
サービスが一時停止中であることを報告します。

hService パラメーターは、サービスへのハンドルである必要があります。

SERVICE_NOTIFY_PAUSED
0x00000040
サービスが一時停止したときに報告します。

hService パラメーターは、サービスへのハンドルである必要があります。

SERVICE_NOTIFY_RUNNING
0x00000008
サービスの実行中にレポートを作成します。

hService パラメーターは、サービスへのハンドルである必要があります。

SERVICE_NOTIFY_START_PENDING
0x00000002
サービスの開始時にレポートを作成します。

hService パラメーターは、サービスへのハンドルである必要があります。

SERVICE_NOTIFY_STOP_PENDING
0x00000004
サービスが停止しているときに報告します。

hService パラメーターは、サービスへのハンドルである必要があります。

SERVICE_NOTIFY_STOPPED
0x00000001
サービスが停止したときに報告します。

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

大事な 呼び出し元のスレッドが DLL 内にあり、スレッドが通知を受け取るか CloseServiceHandle を呼び出す前に DLL がアンロードされた場合、通知によって予期しない結果が発生し、プロセスの応答が停止する可能性があります。
 

注意

winsvc.h ヘッダーは NotifyServiceStatusChange をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件
サポートされている最小のクライアント Windows Vista [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows Server 2008 [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー winsvc.h (Windows.h を含む)
Library Advapi32.lib
[DLL] Advapi32.dll

こちらもご覧ください

SERVICE_NOTIFY

SubscribeServiceChangeNotifications

サービス関数