RegisterServiceCtrlHandlerA 関数 (winsvc.h)

[アーティクル]
03/13/2024

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

この関数は RegisterServiceCtrlHandlerEx 関数に置き換わりました。サービスはどちらの関数も使用できますが、新しい関数はユーザー定義のコンテキストデータをサポートし、新しいハンドラー関数は追加の拡張コントロールコードをサポートします。

構文

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerA(
  [in] LPCSTR             lpServiceName,
  [in] LPHANDLER_FUNCTION lpHandlerProc
);

パラメーター

[in] lpServiceName

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

サービスの種類がSERVICE_WIN32_OWN_PROCESS場合、プロセスに登録されたサービスが 1 つしかないため、指定された名前が有効かどうかは検証されません。

[in] lpHandlerProc

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

戻り値

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

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

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

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

注釈

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

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

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

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

例

例については、「 ServiceMain 関数の記述」を参照してください。

注意

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

要件

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