RegisterServiceCtrlHandlerExA 関数 (winsvc.h)

[アーティクル]
08/27/2023

拡張サービス制御要求を処理する関数を登録します。

構文

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerExA(
  [in]           LPCSTR                lpServiceName,
  [in]           LPHANDLER_FUNCTION_EX lpHandlerProc,
  [in, optional] LPVOID                lpContext
);

パラメーター

[in] lpServiceName

呼び出し元スレッドによって実行されるサービスの名前。これは、サービスの作成時に CreateService 関数でサービス制御プログラムが指定したサービス名です。

[in] lpHandlerProc

登録するハンドラー関数へのポインター。詳細については、「 HandlerEx」を参照してください。

[in, optional] lpContext

ユーザー定義データ。ハンドラー関数に渡されるこのパラメーターは、複数のサービスがプロセスを共有するときにサービスを識別するのに役立ちます。

戻り値

関数が成功した場合、戻り値はサービス状態ハンドルです。

関数が失敗した場合は、0 を返します。詳細なエラー情報を得るには、GetLastError を呼び出します。

サービスコントロールマネージャーでは、次のエラーコードを設定できます。

リターンコード	説明
ERROR_NOT_ENOUGH_MEMORY	ANSI 文字列パラメーターを Unicode に変換するのに十分なメモリがありません。このエラーは、Unicode 文字列パラメーターでは発生しません。
ERROR_SERVICE_NOT_IN_EXE	プロセスが StartServiceCtrlDispatcher 関数を呼び出したときに、サービスエントリが正しく指定されませんでした。

注釈

新しいサービスの ServiceMain 関数は、 RegisterServiceCtrlHandlerEx 関数を直ちに呼び出して、コントロールディスパッチャーにコントロールハンドラー関数を登録する必要があります。これにより、コントロールディスパッチャーは、このサービスのコントロール要求を受信したときに、指定された関数を呼び出すことができます。使用可能なコントロールコードの一覧については、「 HandlerEx」を参照してください。呼び出し元プロセスのスレッドは、この関数によって返されるサービス状態ハンドルを使用して、 SetServiceStatus 関数の後続の呼び出しでサービスを識別できます。

RegisterServiceCtrlHandlerEx 関数は、最初の SetServiceStatus 呼び出しの前に呼び出す必要があります。これは、RegisterServiceCtrlHandlerEx が呼び出し元が使用するサービス状態ハンドルを返し、他のサービスがこのサービスの状態を誤って設定できないようにするためです。さらに、 SetServiceStatus 関数を介して受け入れるコントロールがサービスによって指定されるまでに、コントロール要求を受信するには、コントロールハンドラーを配置する必要があります。

コントロール要求を使用してコントロールハンドラー関数が呼び出されると、サービスは SetServiceStatus を呼び出して、サービスの状態が変更された場合 (サービスが停止コントロールやシャットダウンコントロールを処理している場合など) にのみ、サービスコントロールマネージャーに状態を報告する必要があります。サービスの状態が変更されていない場合、サービスはサービスコントロールマネージャーに状態を報告しないようにする必要があります。

サービス状態ハンドルを閉じる必要はありません。

注意

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

要件

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