StartServiceCtrlDispatcherA 関数 (winsvc.h)

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

サービスプロセスのメインスレッドをサービスコントロールマネージャーに接続します。これにより、スレッドが呼び出し元プロセスのサービスコントロールディスパッチャースレッドになります。

構文

BOOL StartServiceCtrlDispatcherA(
  [in] const SERVICE_TABLE_ENTRYA *lpServiceStartTable
);

パラメーター

[in] lpServiceStartTable

呼び出し元のプロセスで実行できるサービスごとに 1 つのエントリを含むSERVICE_TABLE_ENTRY構造体の配列へのポインター。テーブルの最後のエントリのメンバーには、テーブルの末尾を指定する NULL 値が必要です。

戻り値

関数が成功すると、戻り値は 0 以外になります。

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

次のエラーコードは、サービスコントロールマネージャーによって設定できます。その他のエラーコードは、サービスコントロールマネージャーによって呼び出されるレジストリ関数によって設定できます。

リターンコード	説明
ERROR_FAILED_SERVICE_CONTROLLER_CONNECT	このエラーは、プログラムがサービスとしてではなくコンソールアプリケーションとして実行されている場合に返されます。デバッグ目的でプログラムをコンソールアプリケーションとして実行する場合は、このエラーが返されるときにサービス固有のコードが呼び出されないように構成します。
ERROR_INVALID_DATA	指定されたディスパッチテーブルには、適切な形式ではないエントリが含まれています。
ERROR_SERVICE_ALREADY_RUNNING	このプロセスでは、 StartServiceCtrlDispatcher が既に呼び出されています。各プロセスでは、 StartServiceCtrlDispatcher を 1 回だけ呼び出すことができます。

注釈

サービスコントロールマネージャーは、サービスプロセスを開始すると、 プロセスが StartServiceCtrlDispatcher 関数を呼び出すのを待機します。サービスプロセスのメインスレッドは、起動後 (30 秒以内) にできるだけ早くこの呼び出しを行う必要があります。 StartServiceCtrlDispatcher が成功すると、呼び出し元のスレッドがサービスコントロールマネージャーに接続され、プロセスで実行中のすべてのサービスがSERVICE_STOPPED状態になるまで戻りません。サービスコントロールマネージャーは、この接続を使用して、サービスプロセスのメインスレッドに制御要求とサービス開始要求を送信します。メインスレッドは、適切な HandlerEx 関数を呼び出して制御要求を処理するか、新しいサービスが開始されたときに適切な ServiceMain 関数を実行する新しいスレッドを作成することによって、ディスパッチャーとして機能します。

lpServiceTable パラメーターには、呼び出し元プロセスで実行できる各サービスのエントリが含まれています。各エントリは、そのサービスの ServiceMain 関数を指定します。 SERVICE_WIN32_SHARE_PROCESS サービスの場合、各エントリにはサービスの名前が含まれている必要があります。この名前は、サービスのインストール時に CreateService 関数で指定されたサービス名です。 SERVICE_WIN32_OWN_PROCESS サービスの場合、テーブルエントリのサービス名は無視されます。

サービスが独自のプロセスで実行されている場合、サービスプロセスのメインスレッドは直ちに StartServiceCtrlDispatcher を呼び出す必要があります。初期化タスクはすべて、サービスの起動時にサービスの ServiceMain 関数で実行されます。

複数のサービスがプロセスを共有し、ServiceMain 関数が呼び出される前に一般的なプロセス全体の初期化を行う必要がある場合、メインスレッドは StartServiceCtrlDispatcher を呼び出す前に、30 秒未満で作業を実行できます。それ以外の場合は、プロセス全体の初期化を行うために別のスレッドを作成する必要があります。一方、メインスレッドは StartServiceCtrlDispatcher を呼び出し、サービスコントロールディスパッチャーになります。サービス固有の初期化は、個々のサービスメイン関数で引き続き実行する必要があります。

サービスは、ユーザーインターフェイスを直接表示しようとしないでください。詳細については、「対話型サービス」を参照してください。

例

例については、「サービスプログラムの Main 関数の記述」を参照してください。

注意

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

要件

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