RegisterServiceCtrlHandlerExW 函数 (winsvc.h)

项目
03/04/2024

注册用于处理扩展服务控制请求的函数。

语法

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerExW(
  [in]           LPCWSTR               lpServiceName,
  [in]           LPHANDLER_FUNCTION_EX lpHandlerProc,
  [in, optional] LPVOID                lpContext
);

参数

[in] lpServiceName

由调用线程运行的服务的名称。这是创建服务时 CreateService 函数中指定的服务控制程序的服务名称。

[in] lpHandlerProc

指向要注册的处理程序函数的指针。有关详细信息，请参阅 HandlerEx。

[in, optional] lpContext

任何用户定义的数据。此参数传递给处理程序函数，当多个服务共享一个进程时，可帮助标识服务。

返回值

如果函数成功，则返回值为服务状态句柄。

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

服务控制管理器可以设置以下错误代码。

返回代码	说明
ERROR_NOT_ENOUGH_MEMORY	内存不足，无法将 ANSI 字符串参数转换为 Unicode。 Unicode 字符串参数不会发生此错误。
ERROR_SERVICE_NOT_IN_EXE	进程调用 StartServiceCtrlDispatcher 函数时，未正确指定服务条目。

注解

新服务的 ServiceMain 函数应立即调用 RegisterServiceCtrlHandlerEx 函数，以便向控件调度程序注册控件处理程序函数。这使控制调度程序能够在收到此服务的控制请求时调用指定的函数。有关可能的控制代码的列表，请参阅 HandlerEx。调用进程的线程可以使用此函数返回的服务状态句柄来标识对 SetServiceStatus 函数的后续调用中的服务。

RegisterServiceCtrlHandlerEx 函数必须在第一次 SetServiceStatus 调用之前调用，因为 RegisterServiceCtrlHandlerEx 返回调用方要使用的服务状态句柄，因此其他服务无法无意中设置此服务状态。此外，在服务指定它通过 SetServiceStatus 函数接受的控件时，控件处理程序必须就位以接收控制请求。

使用控制请求调用控件处理程序函数时，服务必须调用 SetServiceStatus ，以便仅当服务状态已更改时（例如，当服务正在处理停止或关闭控件时）向服务控制管理器报告状态。如果服务状态未更改，则服务不应向服务控制管理器报告状态。

无需关闭服务状态句柄。

注意

winsvc.h 标头将 RegisterServiceCtrlHandlerEx 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。有关详细信息，请参阅函数原型的约定。

要求

要求	值
最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	winsvc.h (包括 Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll