次の方法で共有

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

必要条件

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

関連項目

CreateService の

ハンドラーの

RegisterServiceCtrlHandlerEx の

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

サービス関数の

ServiceMain の

SetServiceStatus の

  • Last updated on