ControlService 函式 (winsvc.h)
將控件程式代碼傳送至服務。
若要在停止服務時指定其他資訊，請使用 ControlServiceEx 函式。
語法
BOOL ControlService(
[in] SC_HANDLE hService,
[in] DWORD dwControl,
[out] LPSERVICE_STATUS lpServiceStatus
);
參數
[in] hService
服務的句柄。 OpenService 或 CreateService 函式會傳回此句柄。 此句柄所需的 訪問許可權 取決於要求的 dwControl 程式代碼。
[in] dwControl
此參數可以是下列其中一個控制程序代碼。
此值也可以是使用者定義的控件程序代碼，如下表所述。
| 控制程序代碼 | 意義 |
|---|---|
|
服務會定義與控件程式代碼相關聯的動作。 hService 句柄必須具有SERVICE_USER_DEFINED_CONTROL訪問許可權。 |
[out] lpServiceStatus
接收最新服務狀態資訊的 SERVICE_STATUS 結構的指標。 傳回的資訊反映服務回報給服務控制管理員的最新狀態。
只有在 GetLastError 傳回下列其中一個錯誤碼時，服務控制管理員才會填入結構： NO_ERROR、 ERROR_INVALID_SERVICE_CONTROL、 ERROR_SERVICE_CANNOT_ACCEPT_CTRL或 ERROR_SERVICE_NOT_ACTIVE。 否則，結構不會填入。
傳回值
如果函式成功，則傳回非零的值。
如果此函式失敗，則傳回值為零。 若要取得擴充的錯誤資訊，請呼叫 GetLastError。
服務控制管理員可以設定下列錯誤碼。 服務控制管理員所呼叫的登錄函式可以設定其他錯誤碼。
| 傳回碼 | Description |
|---|---|
|
句柄沒有必要的存取權。 |
|
因為其他執行中的服務相依於服務，所以無法停止服務。 |
|
未使用 CreateService 或 OpenService 取得指定的句柄，或者句柄不再有效。 |
|
要求的控制項程式代碼未定義。 |
|
要求的控制碼無效，或是服務不接受此控制碼。 |
|
要求的控制程式代碼無法傳送至服務，因為服務的狀態是 SERVICE_STOPPED、 SERVICE_START_PENDING或 SERVICE_STOP_PENDING。 |
|
尚未啟動服務。 |
|
服務的進程已啟動，但未呼叫 StartServiceCtrlDispatcher，或呼叫 StartServiceCtrlDispatcher 的線程可能會在控制處理程式函式中遭到封鎖。 |
|
系統正在關閉。 |
備註
ControlService 函式會要求服務控制管理員 (SCM) ，將要求的控件程式代碼傳送至服務。 如果服務已指定接受程式碼，且處於控件程式碼可以傳送至它的狀態，則 SCM 會傳送程式代碼。
SCM 會以序列方式處理服務控制通知，它會等待一個服務完成處理服務控制通知，再傳送下一個服務。 因此，如果有任何服務忙碌處理控件程序代碼， 則 ControlService 的呼叫會封鎖 30 秒。 如果當逾時到期時，忙碌服務仍然未從其處理程式函式傳回， ControlService 會失敗並 ERROR_SERVICE_REQUEST_TIMEOUT。
若要停止和啟動服務，需要可讓您執行此動作的安全性描述元。 默認安全性描述元允許 LocalSystem 帳戶，以及 Administrators 和 Power Users 群組的成員停止和啟動服務。 若要變更服務的安全性描述元，請參閱 修改服務的 DACL。
QueryServiceStatusEx 函式會傳回SERVICE_STATUS_PROCESS結構，其 dwCurrentState 和 dwControlsAccepted 成員表示執行中服務接受的目前狀態和控件。 所有執行中的服務預設都會接受 SERVICE_CONTROL_INTERROGATE 控制程式代碼。 驅動程式不接受 SERVICE_CONTROL_STOP 和 SERVICE_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 |