ControlServiceExA 函数 (winsvc.h)
将控制代码发送到服务。
语法
BOOL ControlServiceExA(
[in] SC_HANDLE hService,
[in] DWORD dwControl,
[in] DWORD dwInfoLevel,
[in, out] PVOID pControlParams
);
参数
[in] hService
服务的句柄。 此句柄由 OpenService 或 CreateService 函数返回。 此句柄所需的 访问权限 取决于请求的 dwControl 代码。
[in] dwControl
此参数可以是以下控制代码之一。
此参数也可以是用户定义的控件代码，如下表所述。
| 控制代码 | 含义 |
|---|---|
|
服务定义与控件代码关联的操作。 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。
服务控制管理器可以设置以下错误代码。 其他错误代码可由服务控制管理器调用的注册表函数设置。
| 返回代码 | 说明 |
|---|---|
|
句柄没有所需的访问权限。 |
|
无法停止该服务，因为其他正在运行的服务都依赖于它。 |
|
未使用 CreateService 或 OpenService 获取指定的句柄，或者该句柄不再有效。 |
|
dwControl 参数中请求的控制代码未定义，或者 dwControl SERVICE_CONTROL_STOP但 SERVICE_CONTROL_STATUS_REASON_PARAMS 结构的 dwReason 或 pszComment 成员无效。 |
|
请求的控制代码无效或服务无法接受该控制代码。 |
|
无法将请求的控制代码发送到服务，因为服务的状态是SERVICE_STOPPED、SERVICE_START_PENDING或SERVICE_STOP_PENDING。 |
|
该服务尚未启动。 |
|
服务的进程已启动，但它未调用 StartServiceCtrlDispatcher，或者调用 StartServiceCtrlDispatcher 的线程可能会在控件处理程序函数中被阻止。 |
|
系统正在关闭。 |
备注
ControlServiceEx 函数要求服务控制管理器 (SCM) 将请求的控制代码发送到服务。 如果服务已指定它将接受代码，并且处于可向其发送控制代码的状态，则 SCM 会发送代码。
SCM 以串行方式处理服务控制通知 - 它会等待一个服务完成服务控制通知的处理，然后再发送下一个服务控制通知。 因此，如果任何服务忙于处理控件代码，则对 ControlServiceEx 的调用会阻止 30 秒。 如果在超时过期时忙服务仍未从其处理程序函数返回， 则 ControlServiceEx 将失败并ERROR_SERVICE_REQUEST_TIMEOUT。
若要停止和启动服务，需要一个允许执行此操作的安全描述符。 默认安全描述符允许 LocalSystem 帐户以及管理员组和 Power Users 组的成员停止和启动服务。 若要更改服务的安全描述符，请参阅 修改服务的 DACL。
QueryServiceStatusEx 函数返回一个 SERVICE_STATUS_PROCESS 结构，其 dwCurrentState 和 dwControlsAccepted 成员指示正在运行的服务接受的当前状态和控件。 默认情况下，所有正在运行的服务都接受SERVICE_CONTROL_INTERROGATE控制代码。 驱动程序不接受SERVICE_CONTROL_STOP和SERVICE_CONTROL_INTERROGATE以外的控制代码。 每个服务指定它在调用 SetServiceStatus 函数以报告其状态时接受的其他控制代码。 服务在运行时应始终接受这些代码，无论它执行什么操作。
下表显示了 SCM 在每个可能的服务状态中的操作。
| 服务状态 | 停止 | 其他控件 |
|---|---|---|
| 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) |
| Library | Advapi32.lib |
| DLL | Advapi32.dll |