RegisterServiceCtrlHandlerW 函数 (winsvc.h)

项目
08/27/2023

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

此函数已被 RegisterServiceCtrlHandlerEx 函数取代。服务可以使用任一函数，但新函数支持用户定义的上下文数据，新的处理程序函数支持其他扩展控制代码。

语法

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerW(
  [in] LPCWSTR            lpServiceName,
  [in] LPHANDLER_FUNCTION lpHandlerProc
);

参数

[in] lpServiceName

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

如果服务类型SERVICE_WIN32_OWN_PROCESS，则函数不会验证指定名称是否有效，因为进程中只有一个已注册的服务。

[in] lpHandlerProc

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

返回值

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

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

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

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

注解

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

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

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

无需关闭服务状态句柄。

示例

有关示例，请参阅编写 ServiceMain 函数。

注意

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

要求


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