SubscribeServiceChangeNotifications function

Article
01/07/2021

Subscribes for service status change notifications using a callback function.

Syntax

DWORD WINAPI SubscribeServiceChangeNotifications(
  _In_     SC_HANDLE                     hService,
  _In_     SC_EVENT_TYPE                 eEventType,
  _In_     PSC_NOTIFICATION_CALLBACK     pCallback,
  _In_opt_ PVOID                         pCallbackContext,
  _Out_    PSC_NOTIFICATION_REGISTRATION *pSubscription
);

Parameters

hService [in]

A handle to the service or a handle to the service control manager (SCM) to monitor for changes.

Handles to services are returned by the OpenService and 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.

eEventType [in]

Specifies the type of status changes that should be reported. This parameter is set to one of the values specified in SC_EVENT_TYPE. The behavior for this function is different depending on the event type as follows.

Value	Meaning
SC_EVENT_DATABASE_CHANGE 0	A service has been added or deleted. The hService parameter must be a handle to the SCM.
SC_EVENT_PROPERTY_CHANGE 1	One or more service properties have been updated. The hService parameter must be a handle to the service.
SC_EVENT_STATUS_CHANGE 2	The status of a service has changed. The hService parameter must be a handle to the service.

pCallback [in]

Specifies the callback function. The callback must be defined as having a type of SC_NOTIFICATION_CALLBACK. For more information, see Remarks.

pCallbackContext [in, optional]

A pointer representing the context for this notification callback.

pSubscription [out]

Returns a pointer to the subscription resulting from the notification callback registration. The caller is responsible for calling UnsubscribeServiceChangeNotifications to stop receiving notifications.

Return value

If the function succeeds, the return value is ERROR_SUCCESS.

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

Remarks

The callback function is declared as follows:

typedef VOID CALLBACK SC_NOTIFICATION_CALLBACK(
    _In_    DWORD                   dwNotify,
    _In_    PVOID                   pCallbackContext
);
typedef SC_NOTIFICATION_CALLBACK* PSC_NOTIFICATION_CALLBACK;

The callback function receives a pointer to the context provided by the caller. The callback is invoked as a result of the service status change event. When the callback is invoked, it is provided with a bitmask of SERVICE_NOTIFY_XXX values that indicating the type of service status change. When the callback is provided with zero instead of a valid SERVICE_NOTIFY_XXX value, the application must verify what was changed.

The callback function must not block execution. If you expect the execution of the callback function to take time, offload the work that you perform in the callback function to a separate thread by queuing a work item to a thread in a thread pool. Some types of work that can make the callback function take time include performing file I/O, waiting on an event, and making external remote procedure calls.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Header	Winsvcp.h
DLL	SecHost.dll