SetServiceStatus

The SetServiceStatus function updates the service control manager's status information for the calling service.

BOOL SetServiceStatus(  SERVICE_STATUS_HANDLE hServiceStatus,  LPSERVICE_STATUS lpServiceStatus);

Parameters

hServiceStatus

[in] Handle to the status information structure for the current service. This handle is returned by the RegisterServiceCtrlHandlerEx function.

lpServiceStatus

[in] Pointer 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.

The following error codes can be set by the service control manager. Other error codes can be set by the registry functions that are called by the service control manager.

Return codeDescriptionERROR_INVALID_DATAThe specified service status structure is invalid.ERROR_INVALID_HANDLEThe specified handle is invalid.

Remarks

A ServiceMain function first calls the RegisterServiceCtrlHandlerEx function to get the service's SERVICE_STATUS_HANDLE. Then it immediately calls the SetServiceStatus function to notify the service control manager that its status is SERVICE_START_PENDING. During initialization, the service can provide updated status to indicate that it is making progress but it needs more time. A common bug is for the service to have the main thread perform the initialization while a separate thread continues to call SetServiceStatus to prevent the service control manager from marking it as hung. However, if the main thread hangs, then the service start ends up in an infinite loop because the worker thread continues to report that the main thread is making progress.

When a service receives a control request, the service's Handler function must call SetServiceStatus, 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.
• Fatal error updates that occur when the service must stop due to a recoverable error.

A service can call this function only after it has called RegisterServiceCtrlHandlerEx to get a service status handle.

If a service calls SetServiceStatus with the dwCurrentState member set to SERVICE_STOPPED and the dwWin32ExitCode member set to a nonzero value, the following entry is written into the System event log:

   Event ID    = 7023   Source      = Service Control Manager   Type        = Error   Description = <ServiceName> terminated with the following error:                 <ExitCode>.

Example Code

For an example, see Writing a ServiceMain Function.

Requirements

ClientRequires Windows XP, Windows 2000 Professional, or Windows NT Workstation.ServerRequires Windows Server 2003, Windows 2000 Server, or Windows NT Server.Header

Declared in Winsvc.h; include Windows.h.

Library

Link to Advapi32.lib.

DLLRequires Advapi32.dll.