RegisterServiceCtrlHandlerA 関数 (winsvc.h)

  • [アーティクル]

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

この関数は 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

こちらもご覧ください

CreateService

Handler

RegisterServiceCtrlHandlerEx

サービス コントロール ハンドラー関数

サービス関数

ServiceMain

SetServiceStatus