The RegisterServiceCtrlHandler function registers a function to handle service control requests for a service.
SERVICE_STATUS_HANDLE RegisterServiceCtrlHandler(
| LPCTSTR lpServiceName, | // address of name of service |
| LPHANDLER_FUNCTION lpHandlerProc | // address of handler function |
| ); |
Parameters
lpServiceName
Points to a null-terminated string that names the service run by the calling thread. This is the service name that was specified in the CreateService function when the service was created.
lpHandlerProc
Points to the Handler function to be registered.
Return Values
If the function succeeds, the return value is a service status handle.
If the function fails, the return value is zero. To get extended error information, call GetLastError.
Errors
The following error codes may be set by the service control manager. Other error codes may be set by the registry functions that are called by the service control manager.
| Value | Meaning |
| ERROR_INVALID_NAME | The specified service name is invalid. |
| ERROR_SERVICE_DOES_NOT_EXIST | The specified service does not exist. |
Remarks
The ServiceMain function of a new service should immediately call the RegisterServiceCtrlHandler function to register a control handling function with the control dispatcher. This enables the control dispatcher to invoke the specified function when it receives control requests for this service. The threads of the calling process can use the service status handle returned by this function to identify the service in subsequent calls to the SetServiceStatus function.
This function must be called before the first SetServiceStatus call because it returns a service status handle for the caller to use so that no other service can inadvertently set this service's status, which is maintained by the service control manager. It also needs to be called before the first SetServiceStatus so that a control handler is in place to field control requests by the time the service specifies the controls it accepts through the SetServiceStatus function.
When the control handler function is invoked with a control request, it must call SetServiceStatus to notify the service control manager of its latest status, regardless of whether the status of the service has changed.
The service status handle does not have to be closed.
See Also