次の方法で共有

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

価値 意味
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 関数は、呼び出し元のスレッドで OpenThread 関数をTHREAD_SET_CONTEXTアクセス権で呼び出します。 呼び出し元のスレッドにこのアクセス権がない場合、NotifyServiceStatusChange は失敗します。 呼び出し元のスレッドが別のユーザーを偽装している場合は、コンテキストを設定するための十分なアクセス許可がない可能性があります。

待機を実行するスレッドから NotifyServiceStatusChange 呼び出す方が、追加のスレッドを作成するよりも効率的です。

コールバック関数が呼び出された後、呼び出し元は NotifyServiceStatusChange 呼び出して、追加の通知を受信する必要があります。 NotifyServiceStatusChange やその他の SCM 関数など、Windows API の特定の関数では、リモート プロシージャ コール (RPC) を使用します。これらの関数は警告可能な待機操作を実行する可能性があるため、コールバック関数内から呼び出しても安全ではありません。 代わりに、コールバック関数は通知パラメーターを保存し、コールバックの外部で追加の作業を実行する必要があります。

未処理の通知を取り消すには、CloseServiceHandle 関数を使用してサービス ハンドルを閉じます。 CloseServiceHandle 成功すると、それ以上通知 API はキューに入れなくなります。 呼び出し元のスレッドがサービス ハンドルを閉じずに終了した場合、または APC が生成されるまで待機しないと、メモリ リークが発生する可能性があります。

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

手記

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

必要条件

要件 価値
サポートされる最小クライアント Windows Vista [デスクトップ アプリのみ]
サポートされる最小サーバー Windows Server 2008 [デスクトップ アプリのみ]
ターゲット プラットフォーム の ウィンドウズ
ヘッダー winsvc.h (Windows.h を含む)
ライブラリ Advapi32.lib
DLL Advapi32.dll

関連項目

SERVICE_NOTIFY

SubscribeServiceChangeNotifications の

サービス関数の