次の方法で共有


ControlService 関数 (winsvc.h)

コントロール コードをサービスに送信します。

サービスを停止するときに追加情報を指定するには、 ControlServiceEx 関数を使用します。

構文

BOOL ControlService(
  [in]  SC_HANDLE        hService,
  [in]  DWORD            dwControl,
  [out] LPSERVICE_STATUS lpServiceStatus
);

パラメーター

[in] hService

サービスへのハンドル。 このハンドルは、 OpenService または CreateService 関数によって返されます。 このハンドルに必要な アクセス権 は、要求された dwControl コードによって異なります。

[in] dwControl

このパラメーターには、次のいずれかの制御コードを指定できます。

制御コード 意味
SERVICE_CONTROL_CONTINUE
0x00000003
一時停止したサービスに再開する必要があることを通知します。 hService ハンドルには、SERVICE_PAUSE_CONTINUEアクセス権が必要です。
SERVICE_CONTROL_INTERROGATE
0x00000004
現在の状態情報をサービス コントロール マネージャーに報告する必要があることをサービスに通知します。 hService ハンドルには、SERVICE_INTERROGATEアクセス権が必要です。

SCM ではサービスの現在の状態が認識されるため、このコントロールは一般的には役に立ちません。

SERVICE_CONTROL_NETBINDADD
0x00000007
バインド用の新しいコンポーネントがあることをネットワーク サービスに通知します。 hService ハンドルには、SERVICE_PAUSE_CONTINUEアクセス権が必要です。 ただし、この制御コードは非推奨となりました。代わりにプラグ アンド プレイ機能を使用してください。
SERVICE_CONTROL_NETBINDDISABLE
0x0000000A
いずれかのバインドが無効になっていることをネットワーク サービスに通知します。 hService ハンドルには、SERVICE_PAUSE_CONTINUEアクセス権が必要です。 ただし、この制御コードは非推奨となりました。代わりにプラグ アンド プレイ機能を使用してください。
SERVICE_CONTROL_NETBINDENABLE
0x00000009
無効なバインディングが有効になっていることをネットワーク サービスに通知します。 hService ハンドルには、SERVICE_PAUSE_CONTINUEアクセス権が必要です。 ただし、この制御コードは非推奨となりました。代わりにプラグ アンド プレイ機能を使用してください。
SERVICE_CONTROL_NETBINDREMOVE
0x00000008
バインド用のコンポーネントが削除されたことをネットワーク サービスに通知します。 hService ハンドルには、SERVICE_PAUSE_CONTINUEアクセス権が必要です。 ただし、この制御コードは非推奨となりました。代わりにプラグ アンド プレイ機能を使用してください。
SERVICE_CONTROL_PARAMCHANGE
0x00000006
スタートアップ パラメーターが変更されたことをサービスに通知します。 hService ハンドルには、SERVICE_PAUSE_CONTINUEアクセス権が必要です。
SERVICE_CONTROL_PAUSE
0x00000002
一時停止する必要があることをサービスに通知します。 hService ハンドルには、SERVICE_PAUSE_CONTINUEアクセス権が必要です。
SERVICE_CONTROL_STOP
0x00000001
停止する必要があることをサービスに通知します。 hService ハンドルには、SERVICE_STOPアクセス権が必要です。

サービスに停止要求を送信した後は、他のコントロールをサービスに送信しないでください。

 

この値は、次の表で説明するように、ユーザー定義のコントロール コードにすることもできます。

制御コード 意味
範囲 128 ~ 255
サービスは、コントロール コードに関連付けられているアクションを定義します。 hService ハンドルには、SERVICE_USER_DEFINED_CONTROLアクセス権が必要です。

[out] lpServiceStatus

最新のサービス状態情報を受信する SERVICE_STATUS 構造体へのポインター。 返される情報には、サービスがサービス 制御マネージャーに報告した最新の状態が反映されます。

サービス コントロール マネージャーは、 GetLastError が 次のいずれかのエラー コードを返す場合にのみ構造体を入力します: NO_ERRORERROR_INVALID_SERVICE_CONTROLERROR_SERVICE_CANNOT_ACCEPT_CTRLまたはERROR_SERVICE_NOT_ACTIVE。 それ以外の場合、構造体は入力されません。

戻り値

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

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

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

リターン コード 説明
ERROR_ACCESS_DENIED
ハンドルには、必要なアクセス権がありません。
ERROR_DEPENDENT_SERVICES_RUNNING
他の実行中のサービスが依存しているため、サービスを停止できません。
ERROR_INVALID_HANDLE
指定したハンドルが CreateService または OpenService を使用して取得されなかったか、ハンドルが無効になりました。
ERROR_INVALID_PARAMETER
要求された制御コードは未定義です。
ERROR_INVALID_SERVICE_CONTROL
要求された制御コードは有効でないか、またはサービスを受け入れ可能ではありません。
ERROR_SERVICE_CANNOT_ACCEPT_CTRL
サービスの状態がSERVICE_STOPPED、SERVICE_START_PENDING、またはSERVICE_STOP_PENDINGであるため、要求された制御コードをサービスに送信できません。
ERROR_SERVICE_NOT_ACTIVE
サービスは開始されていません。
ERROR_SERVICE_REQUEST_TIMEOUT
サービスのプロセスは開始されましたが、 StartServiceCtrlDispatcher を呼び出さなかったか、コントロール ハンドラー関数で StartServiceCtrlDispatcher を呼び出したスレッドがブロックされる可能性があります。
ERROR_SHUTDOWN_IN_PROGRESS
システムがシャットダウンしています。

注釈

ControlService 関数は、要求されたコントロール コードをサービスに送信するようにサービス コントロール マネージャー (SCM) に要求します。 SCM は、サービスがコードを受け入れることを指定しており、コントロール コードを送信できる状態である場合にコードを送信します。

SCM は、サービス制御通知をシリアル形式で処理します。1 つのサービスがサービス制御通知の処理を完了してから次のサービス制御通知を送信するまで待機します。 このため、コントロール コードの処理がビジー状態のサービスがある場合、 ControlService の呼び出しは 30 秒間ブロックされます。 タイムアウトの期限が切れたときにビジー 状態のサービスがハンドラー関数からまだ返されない場合、 ControlServiceERROR_SERVICE_REQUEST_TIMEOUTで失敗します。

サービスを停止して開始するには、それを可能にするセキュリティ記述子が必要です。 既定のセキュリティ記述子を使用すると、 LocalSystem アカウントと、Administrators グループと Power Users グループのメンバーがサービスを停止および開始できます。 サービスのセキュリティ記述子を変更するには、「サービス の DACL の変更」を参照してください。

QueryServiceStatusEx 関数はdwCurrentState メンバーと dwControlsAccepted メンバーが、実行中のサービスによって受け入れられる現在の状態とコントロールを示すSERVICE_STATUS_PROCESS構造体を返します。 実行中のすべてのサービスは、既定で SERVICE_CONTROL_INTERROGATE 制御コードを受け入れます。 ドライバーは、SERVICE_CONTROL_STOPとSERVICE_CONTROL_INTERROGATE以外のコントロール コードを受け入れません。 各サービスは、 SetServiceStatus 関数を呼び出して状態を報告するときに受け入れる他のコントロール コードを指定します。 サービスは、何を行っていても、実行中にこれらのコードを常に受け入れる必要があります。

次の表は、使用可能な各サービス状態における SCM のアクションを示しています。

サービスの状態 Stop その他の制御
STOPPED (c) (c)
STOP_PENDING (b) (b)
START_PENDING (a) (b)
実行 (a) (a)
CONTINUE_PENDING (a) (a)
PAUSE_PENDING (a) (a)
一時 停止 (a) (a)
(a)
サービスがこの制御コードを受け入れる場合は、サービスに要求を送信します。それ以外の場合、ControlService は 0 を返し、GetLastError はERROR_INVALID_SERVICE_CONTROLを返します。
(b)
サービスはコントロールを送信できる状態にないため、ControlService は 0 を返し、GetLastError はERROR_SERVICE_CANNOT_ACCEPT_CTRLを返します。
(c)
サービスはアクティブでないため、ControlService は 0 を返し、GetLastError はERROR_SERVICE_NOT_ACTIVEを返します。

例については、「 サービスの停止」を参照してください。

要件

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

こちらもご覧ください

ControlServiceEx

CreateService

OpenService

QueryServiceStatusEx

SERVICE_STATUS

サービス制御要求

サービス関数

SetServiceObjectSecurity

SetServiceStatus