RegisterServiceCtrlHandlerA 函数（winsvc.h）

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

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

语法

SERVICE_STATUS_HANDLE RegisterServiceCtrlHandlerA(
  [in] LPCSTR             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 [仅限桌面应用]
目标平台	窗户
标头	winsvc.h （包括 Windows.h）
库	Advapi32.lib
DLL	Advapi32.dll