SetServiceStatus
The SetServiceStatus
function updates the service control manager s status information for the
calling service.
BOOL SetServiceStatus(
|
SERVICE_STATUS_HANDLE hServiceStatus~, |
// service status
handle |
|
LPSERVICE_STATUS lpServiceStatus |
// address of
status structure |
|
); |
|
Parameters
hServiceStatus~
Specifies a
handle to the service control manager s status information structure for the
current service. This handle is returned by the RegisterServiceCtrlHandler function.
lpServiceStatus
Points to the
SERVICE_STATUS
structure the contains the latest status information for the calling service.
Return Values
If the
function succeeds, the return value is nonzero.
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_HANDLE |
The
specified handle is invalid. |
|
ERROR_INVALID_DATA |
The
specified service status structure is invalid. |
Remarks
A Win32
service s ServiceMain
function first calls the RegisterServiceCtrlHandler function to get the
service s SERVICE_STATUS_HANDLE. Then it immediately calls the SetServiceStatus
function to notify the service control manager of its SERVICE_START_PENDING
status.
When a Win32
service receives a control request, the service s Handler function must call this
function, even if the service s status did not change. A service can also use
this function at any time and by any thread of the service to notify the
service control manager of status changes. Examples of such unsolicited status
updates include:
Checkpoint updates that occur
when the service is in transition from one state to another (that is,
SERVICE_START_PENDING).
An update made necessary by the
expected occurrence of a fatal error that causes the service to stop.
A service can
call this function only after it has called RegisterServiceCtrlHandler
to get a service status handle.
See Also