NotifyServiceStatusChange function

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

Syntax


DWORD WINAPI NotifyServiceStatusChange(
  _In_  SC_HANDLE hService,
  _In_  DWORD dwNotifyMask,
  _In_  PSERVICE_NOTIFY pNotifyBuffer
);

Parameters

hService [in]

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.

dwNotifyMask [in]

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

ValueMeaning
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.

 

pNotifyBuffer [in]

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.

Requirements

Minimum supported client

Windows Vista [desktop apps only]

Minimum supported server

Windows Server 2008 [desktop apps only]

Header

Winsvc.h (include Windows.h)

Library

Advapi32.lib

DLL

Advapi32.dll

Unicode and ANSI names

NotifyServiceStatusChangeW (Unicode) and NotifyServiceStatusChangeA (ANSI)

See also

Service Functions
SERVICE_NOTIFY

 

 

Community Additions

ADD
Show:
© 2014 Microsoft