RegisterServiceCtrlHandlerExA 関数 (winsvc.h)

  • [アーティクル]

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

構文

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

こちらもご覧ください

CreateService

HandlerEx

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

サービス関数

ServiceMain

SetServiceStatus