3.1.4.38 RQueryServiceStatusEx (Opnum 40)

  • Article

The RQueryServiceStatusEx method returns the current status of the specified service, based on the specified information level.

 DWORD RQueryServiceStatusEx(
   [in] SC_RPC_HANDLE hService,
   [in] SC_STATUS_TYPE InfoLevel,
   [out, size_is(cbBufSize)] LPBYTE lpBuffer,
   [in, range(0, 1024*8)] DWORD cbBufSize,
   [out] LPBOUNDED_DWORD_8K pcbBytesNeeded
 );

hService: An SC_RPC_HANDLE (section 2.2.4) data type that defines the handle to the service record that MUST have been created previously, using one of the open methods specified in section 3.1.4. The SERVICE_QUERY_STATUS access right MUST have been granted to the caller when the RPC context handle to the service record was created.

InfoLevel: An enumerated value from SC_STATUS_TYPE (section 2.2.29) that specifies which service attributes are returned. MUST be SC_STATUS_PROCESS_INFO.

lpBuffer: A pointer to the buffer that contains the status information in the form of a SERVICE_STATUS_PROCESS (section 2.2.49) structure.

cbBufSize: The size, in bytes, of the lpBuffer parameter.

pcbBytesNeeded: An LPBOUNDED_DWORD_8K (section 2.2.8) data type that defines the pointer to a variable that contains the number of bytes needed to return the configuration information.

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

87

ERROR_INVALID_PARAMETER

A parameter that was specified is invalid.

122

ERROR_INSUFFICIENT_BUFFER

The data area passed to a system call is too small.

124

ERROR_INVALID_LEVEL

The InfoLevel parameter contains an unsupported value.

1115

ERROR_SHUTDOWN_IN_PROGRESS

The system is shutting down.

In response to this request from the client, for a successful operation the server MUST query the configuration information as specified and stored in the SCM database associated with the service record identified by the hService parameter. The server MUST return this configuration data by setting the lpBuffer parameter with the SERVICE_STATUS_PROCESS structure filled with the configuration data as specified in section 2.2.49.

If the buffer pointed to by lpBuffer is insufficient to hold all the configuration data, the server MUST fail the call with ERROR_INSUFFICIENT_BUFFER (122) and set the required buffer size in the pcbBytesNeeded parameter.