3.1.4.43 RNotifyServiceStatusChange (Opnum 47)

  • Article

The RNotifyServiceStatusChange method<74> allows the client to register for notifications and check, via RGetNotifyResults (section 3.1.4.44), when the specified service of type SERVICE_WIN32_OWN_PROCESS or SERVICE_WIN32_SHARE_PROCESS is created or deleted or when its status changes.

 DWORD RNotifyServiceStatusChange(
   [in] SC_RPC_HANDLE hService,
   [in] SC_RPC_NOTIFY_PARAMS NotifyParams,
   [in] GUID* pClientProcessGuid,
   [out] GUID* pSCMProcessGuid,
   [out] PBOOL pfCreateRemoteQueue,
   [out] LPSC_NOTIFY_RPC_HANDLE phNotify
 );

hService: An SC_RPC_HANDLE data type that defines the handle to the SCM for SERVICE_NOTIFY_CREATED and SERVICE_NOTIFY_DELETED notifications or to the service record for all other notification types that MUST have been created previously, using one of the open methods specified in section 3.1.4. The SC_MANAGER_ENUMERATE_SERVICE access right MUST have been granted to the caller when the RPC context handle to the SCM was created, or the SERVICE_QUERY_STATUS access right MUST have been granted to the caller when the RPC context handle to the service record was created.

NotifyParams: An SC_RPC_NOTIFY_PARAMS (section 2.2.23) data type that defines the service status notification information.

pClientProcessGuid: Not used. This MUST be ignored.

pSCMProcessGuid: Not used. This MUST be ignored.

pfCreateRemoteQueue: Not used. This MUST be ignored.

phNotify: An LPSC_NOTIFY_RPC_HANDLE (section 2.2.6) data type that defines a handle to the notification status associated with the client for the specified service.

Return Values: The method returns 0x00000000 (ERROR_SUCCESS) on success; otherwise, it returns one of the following error codes.

Return value/code

Description

5

ERROR_ACCESS_DENIED

The SC_MANAGER_ENUMERATE_SERVICE access right had not been granted to the caller when the RPC context handle to the SCM was created, or the SERVICE_QUERY_STATUS access right had not been granted to the caller when the RPC context handle to the service record was created.

6

ERROR_INVALID_HANDLE

The handle is no longer valid or is not supported for the specified notification.

50

ERROR_NOT_SUPPORTED

The request is not supported.

87

ERROR_INVALID_PARAMETER

A parameter that was specified is invalid.

124

ERROR_INVALID_LEVEL

The system call level is not correct.

1072

ERROR_SERVICE_MARKED_FOR_DELETE

The RDeleteService has been called for the service record identified by the hService parameter.

1115

ERROR_SHUTDOWN_IN_PROGRESS

The system is shutting down.

1242

ERROR_ALREADY_REGISTERED

A notification status handle has already been created for the service handle passed in the hService parameter.

1294

ERROR_SERVICE_NOTIFY_CLIENT_LAGGING

The service notification client is lagging too far behind the current state of services in the machine.

In response to this request from the client, for a successful operation, the server MUST associate NOTIFY_RPC_HANDLE for the caller to check for status changes using RGetNotifyResults for the service record identified by the hService parameter.

The server MUST ignore any value set in the ullThreadId parameter in NotifyParams.

The server MUST fail the call and return ERROR_INVALID_PARAMETER if dwNotifyMask contains masks for both create/delete events and service status events.

The client can set the value of pClientProcessGuid, pSCMProcessGuid, and pfCreatRemoteQueue to any value, such as 0, and the server MUST ignore these.

The server MUST return ERROR_NOT_SUPPORTED (50) if the value of dwInfoLevel is greater than SERVICE_NOTIFY_STATUS_CHANGE.

The server MUST return ERROR_INVALID_LEVEL (124) if the value of dwInfoLevel is not SERVICE_NOTIFY_STATUS_CHANGE (0x2) or SERVICE_NOTIFY_STATUS_CHANGE_1 (0x1).