SetServiceStatus

最新推荐文章于 2024-01-12 16:27:49 发布

原创最新推荐文章于 2024-01-12 16:27:49 发布 · 2.5k 阅读

0 ·

CC 4.0 BY-SA版权

文章标签：

#service #function #structure #initialization #manager #thread

本文详细介绍了SetServiceStatus函数，该函数用于更新服务控制管理器中调用服务的状态信息。文中说明了其参数、返回值，指出成功时返回非零值，失败为零。还阐述了使用该函数的注意事项，如服务初始化时的状态通知、控制请求时的调用等，并给出示例和要求。

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 code	Description
ERROR_INVALID_DATA	The specified service status structure is invalid.
ERROR_INVALID_HANDLE	The 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

Client	Requires Windows XP, Windows 2000 Professional, or Windows NT Workstation.
Server	Requires Windows Server 2003, Windows 2000 Server, or Windows NT Server.
Header	Declared in Winsvc.h; include Windows.h.
Library	Link to Advapi32.lib.
DLL	Requires Advapi32.dll.