NotifyServiceStatusChangeA function (winsvc.h)

Article
02/09/2023

Enables an application to receive notification when the specified service is created or deleted or when its status changes.

Syntax

DWORD NotifyServiceStatusChangeA(
  [in] SC_HANDLE        hService,
  [in] DWORD            dwNotifyMask,
  [in] PSERVICE_NOTIFYA pNotifyBuffer
);

Parameters

[in] hService

A handle to the service or the service control manager. Handles to services are returned by the OpenService or CreateService function and must have the SERVICE_QUERY_STATUS access right. Handles to the service control manager are returned by the OpenSCManager function and must have the SC_MANAGER_ENUMERATE_SERVICE access right. For more information, see Service Security and Access Rights.

There can only be one outstanding notification request per service.

[in] dwNotifyMask

The type of status changes that should be reported. This parameter can be one or more of the following values.

Value	Meaning
SERVICE_NOTIFY_CREATED 0x00000080	Report when the service has been created. The hService parameter must be a handle to the SCM.
SERVICE_NOTIFY_CONTINUE_PENDING 0x00000010	Report when the service is about to continue. The hService parameter must be a handle to the service.
SERVICE_NOTIFY_DELETE_PENDING 0x00000200	Report when an application has specified the service in a call to the DeleteService function. Your application should close any handles to the service so it can be deleted. The hService parameter must be a handle to the service.
SERVICE_NOTIFY_DELETED 0x00000100	Report when the service has been deleted. An application cannot receive this notification if it has an open handle to the service. The hService parameter must be a handle to the SCM.
SERVICE_NOTIFY_PAUSE_PENDING 0x00000020	Report when the service is pausing. The hService parameter must be a handle to the service.
SERVICE_NOTIFY_PAUSED 0x00000040	Report when the service has paused. The hService parameter must be a handle to the service.
SERVICE_NOTIFY_RUNNING 0x00000008	Report when the service is running. The hService parameter must be a handle to the service.
SERVICE_NOTIFY_START_PENDING 0x00000002	Report when the service is starting. The hService parameter must be a handle to the service.
SERVICE_NOTIFY_STOP_PENDING 0x00000004	Report when the service is stopping. The hService parameter must be a handle to the service.
SERVICE_NOTIFY_STOPPED 0x00000001	Report when the service has stopped. The hService parameter must be a handle to the service.

[in] pNotifyBuffer

A pointer to a SERVICE_NOTIFY structure that contains notification information, such as a pointer to the callback function. This structure must remain valid until the callback function is invoked or the calling thread cancels the notification request.

Do not make multiple calls to NotifyServiceStatusChange with the same buffer parameter until the callback function from the first call has finished with the buffer or the first notification request has been canceled. Otherwise, there is no guarantee which version of the buffer the callback function will receive.

Windows Vista: The address of the callback function must be within the address range of a loaded module. Therefore, the callback function cannot be code that is generated at run time (such as managed code generated by the JIT compiler) or native code that is decompressed at run time. This restriction was removed in Windows Server 2008 and Windows Vista with SP1.

Return value

If the function succeeds, the return value is ERROR_SUCCESS. If the service has been marked for deletion, the return value is ERROR_SERVICE_MARKED_FOR_DELETE and the handle to the service must be closed. If service notification is lagging too far behind the system state, the function returns ERROR_SERVICE_NOTIFY_CLIENT_LAGGING. In this case, the client should close the handle to the SCM, open a new handle, and call this function again.

If the function fails, the return value is one of the system error codes.

Remarks

The NotifyServiceStatusChange function can be used to receive notifications about service applications. It cannot be used to receive notifications about driver services.

When the service status changes, the system invokes the specified callback function as an asynchronous procedure call (APC) queued to the calling thread. The calling thread must enter an alertable wait (for example, by calling the SleepEx function) to receive notification. For more information, see Asynchronous Procedure Calls.

If the service is already in any of the requested states when NotifyServiceStatusChange is called, the callback function is queued immediately. If the service state has not changed by the next time the function is called with the same service and state, the callback function is not queued immediately; the callback function is queued the next time the service enters the requested state.

The NotifyServiceStatusChange function calls the OpenThread function on the calling thread with the THREAD_SET_CONTEXT access right. If the calling thread does not have this access right, NotifyServiceStatusChange fails. If the calling thread is impersonating another user, it may not have sufficient permission to set context.

It is more efficient to call NotifyServiceStatusChange from a thread that performs a wait than to create an additional thread.

After the callback function is invoked, the caller must call NotifyServiceStatusChange to receive additional notifications. Note that certain functions in the Windows API, including NotifyServiceStatusChange and other SCM functions, use remote procedure calls (RPC); these functions might perform an alertable wait operation, so they are not safe to call from within the callback function. Instead, the callback function should save the notification parameters and perform any additional work outside the callback.

To cancel outstanding notifications, close the service handle using the CloseServiceHandle function. After CloseServiceHandle succeeds, no more notification APCs will be queued. If the calling thread exits without closing the service handle or waiting until the APC is generated, a memory leak can occur.

Important If the calling thread is in a DLL and the DLL is unloaded before the thread receives the notification or calls CloseServiceHandle, the notification will cause unpredictable results and might cause the process to stop responding.

Note

The winsvc.h header defines NotifyServiceStatusChange as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2008 [desktop apps only]
Target Platform	Windows
Header	winsvc.h (include Windows.h)
Library	Advapi32.lib
DLL	Advapi32.dll