RegisterServiceCtrlHandler
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