共用方式為


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_CTRLERROR_SERVICE_NOT_ACTIVE。 否則,結構不會填入。

傳回值

如果函式成功,則傳回非零的值。

如果此函式失敗,則傳回值為零。 若要取得擴充的錯誤資訊,請呼叫 GetLastError

服務控制管理員可以設定下列錯誤碼。 服務控制管理員所呼叫的登錄函式可以設定其他錯誤碼。

傳回碼 Description
ERROR_ACCESS_DENIED
句柄沒有必要的存取權。
ERROR_DEPENDENT_SERVICES_RUNNING
因為其他執行中的服務相依於服務,所以無法停止服務。
ERROR_INVALID_HANDLE
未使用 CreateServiceOpenService 取得指定的句柄,或者句柄不再有效。
ERROR_INVALID_PARAMETER
要求的控制項程式代碼未定義。
ERROR_INVALID_SERVICE_CONTROL
要求的控制碼無效,或是服務不接受此控制碼。
ERROR_SERVICE_CANNOT_ACCEPT_CTRL
要求的控制程式代碼無法傳送至服務,因為服務的狀態是 SERVICE_STOPPEDSERVICE_START_PENDINGSERVICE_STOP_PENDING
ERROR_SERVICE_NOT_ACTIVE
尚未啟動服務。
ERROR_SERVICE_REQUEST_TIMEOUT
服務的進程已啟動,但未呼叫 StartServiceCtrlDispatcher,或呼叫 StartServiceCtrlDispatcher 的線程可能會在控制處理程式函式中遭到封鎖。
ERROR_SHUTDOWN_IN_PROGRESS
系統正在關閉。

備註

ControlService 函式會要求服務控制管理員 (SCM) ,將要求的控件程式代碼傳送至服務。 如果服務已指定接受程式碼,且處於控件程式碼可以傳送至它的狀態,則 SCM 會傳送程式代碼。

SCM 會以序列方式處理服務控制通知,它會等待一個服務完成處理服務控制通知,再傳送下一個服務。 因此,如果有任何服務忙碌處理控件程序代碼, 則 ControlService 的呼叫會封鎖 30 秒。 如果當逾時到期時,忙碌服務仍然未從其處理程式函式傳回, ControlService 會失敗並 ERROR_SERVICE_REQUEST_TIMEOUT

若要停止和啟動服務,需要可讓您執行此動作的安全性描述元。 默認安全性描述元允許 LocalSystem 帳戶,以及 Administrators 和 Power Users 群組的成員停止和啟動服務。 若要變更服務的安全性描述元,請參閱 修改服務的 DACL

QueryServiceStatusEx 函式會傳回SERVICE_STATUS_PROCESS結構,其 dwCurrentStatedwControlsAccepted 成員表示執行中服務接受的目前狀態和控件。 所有執行中的服務預設都會接受 SERVICE_CONTROL_INTERROGATE 控制程式代碼。 驅動程式不接受 SERVICE_CONTROL_STOPSERVICE_CONTROL_INTERROGATE以外的控制程序代碼。 每個服務都會指定它呼叫 SetServiceStatus 函式來報告其狀態時所接受的其他控制件代碼。 無論執行什麼動作,服務都應該一律接受這些程序代碼。

下表顯示每個可能服務狀態中 SCM 的動作。

服務狀態 Stop 其他控制件
STOPPED (c) (c)
STOP_PENDING (b) (b)
START_PENDING () (b)
運行 () ()
CONTINUE_PENDING () ()
PAUSE_PENDING () ()
已暫停 () ()
()
如果服務接受此控制程式代碼,請將要求傳送至服務;否則, ControlService 會傳回零, 而 GetLastError 會傳回 ERROR_INVALID_SERVICE_CONTROL
(b)
服務不是可以傳送控件的狀態,因此 ControlService 會傳回零, 而 GetLastError 會傳回 ERROR_SERVICE_CANNOT_ACCEPT_CTRL
(c)
服務沒有作用中,因此 ControlService 會傳回零,而 GetLastError傳回ERROR_SERVICE_NOT_ACTIVE

範例

如需範例,請參閱 停止服務

規格需求

需求
最低支援的用戶端 Windows XP [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003 [僅限傳統型應用程式]
目標平台 Windows
標頭 winsvc.h (包括 Windows.h)
程式庫 AdvApi32.lib
Dll AdvApi32.dll

另請參閱

ControlServiceEx

CreateService

OpenService

QueryServiceStatusEx

SERVICE_STATUS

服務控制要求

服務函式

SetServiceObjectSecurity

SetServiceStatus