ControlServiceExA 函式 (winsvc.h)

發行項
08/27/2023

將控制項程式碼傳送至服務。

語法

BOOL ControlServiceExA(
  [in]      SC_HANDLE hService,
  [in]      DWORD     dwControl,
  [in]      DWORD     dwInfoLevel,
  [in, out] PVOID     pControlParams
);

參數

[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存取權限。

[in] dwInfoLevel

服務控制參數的資訊層級。此參數必須設定為 SERVICE_CONTROL_STATUS_REASON_INFO (1) 。

[in, out] pControlParams

服務控制項參數的指標。如果 dwInfoLevel 是SERVICE_CONTROL_STATUS_REASON_INFO，則此成員是 SERVICE_CONTROL_STATUS_REASON_PARAMS 結構的指標。

傳回值

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

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

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

傳回碼	描述
ERROR_ACCESS_DENIED	控制碼沒有必要的存取權。
ERROR_DEPENDENT_SERVICES_RUNNING	因為其他執行中的服務相依于服務，所以無法停止服務。
ERROR_INVALID_HANDLE	未使用 CreateService 或 OpenService取得指定的控制碼，或者控制碼不再有效。
ERROR_INVALID_PARAMETER	dwControl參數中要求的控制項程式碼未定義，或dwControl已SERVICE_CONTROL_STOP但SERVICE_CONTROL_STATUS_REASON_PARAMS結構的dwReason或pszComment成員無效。
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	系統正在關閉。

備註

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

SCM 會以序列方式處理服務控制通知，它會等候一個服務完成處理服務控制通知，再傳送下一個服務。因此，如果有任何服務忙碌處理控制項程式碼， 則 ControlServiceEx 的呼叫會封鎖 30 秒。如果逾時到期時，忙碌服務仍然未從其處理常式函式傳回， ControlServiceEx 會失敗並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)
RUNNING	()	()
CONTINUE_PENDING	()	()
PAUSE_PENDING	()	()
已暫停	()	()

(): 如果服務接受此控制程式代碼，請將要求傳送至服務;否則 ，ControlServiceEx 會傳回零，而 GetLastError 會 傳回ERROR_INVALID_SERVICE_CONTROL。
(b): 服務不是可以傳送控制項給它的狀態，因此 ControlServiceEx 會傳回零，而 GetLastError 會 傳回ERROR_SERVICE_CANNOT_ACCEPT_CTRL。
(c): 服務沒有作用中，因此 ControlServiceEx 會傳回零，而 GetLastError 會 傳回ERROR_SERVICE_NOT_ACTIVE。

注意

winsvc.h 標頭會將 ControlServiceEx 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程式碼，可能會導致編譯或執行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求


最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	winsvc.h (包含 Windows.h)
程式庫	Advapi32.lib
Dll	Advapi32.dll