3.1.4.13 REnumDependentServicesW (Opnum 13)

  • Article

The REnumDependentServicesW method returns the ServiceName, DisplayName, and ServiceStatus values of service records that are listed as dependents of a specified service.

 DWORD REnumDependentServicesW(
   [in] SC_RPC_HANDLE hService,
   [in] DWORD dwServiceState,
   [out, size_is(cbBufSize)] LPBYTE lpServices,
   [in, range(0, 1024*256)] DWORD cbBufSize,
   [out] LPBOUNDED_DWORD_256K pcbBytesNeeded,
   [out] LPBOUNDED_DWORD_256K lpServicesReturned
 );

hService: An SC_RPC_HANDLE 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_ENUMERATE_DEPENDENT access right MUST have been granted to the caller when the RPC context handle to the service record was created.

dwServiceState: A value that specifies the service records to enumerate based on the value of their ServiceStatus.dwCurrentState. This MUST be one of the following values.

Value

Meaning

SERVICE_ACTIVE

0x00000001

Enumerates service records that have a ServiceStatus.dwCurrentState equal to one of the following: SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_RUNNING, SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING, and SERVICE_PAUSED.

SERVICE_INACTIVE

0x00000002

Enumerates service records that have a ServiceStatus.dwCurrentState equal to SERVICE_STOPPED.

SERVICE_STATE_ALL

0x00000003

Enumerates service records that have a ServiceStatus.dwCurrentState equal to one of the following: SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_RUNNING, SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING, SERVICE_PAUSED, and SERVICE_STOPPED.

lpServices: A pointer to an array of ENUM_SERVICE_STATUSW (section 2.2.11) structures that contain the name and service status information for each dependent service in the database.

cbBufSize: The size, in bytes, of the array pointed to by lpServices.

pcbBytesNeeded: An LPBOUNDED_DWORD_256K (section 2.2.9) pointer to a variable that contains the number of bytes needed to store the array of service entries.

lpServicesReturned: An LPBOUNDED_DWORD_256K (section 2.2.9) pointer to a variable that contains the number of service entries returned.

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

234

ERROR_MORE_DATA

More data is available.

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 determine the list of service records that depend on the service record identified by the hService parameter of the client request. The server MUST return this list by setting the ServiceName, DisplayName, and ServiceStatus.dwCurrentState of each service record in this list in the array of ENUM_SERVICE_STATUSW (section 2.2.11) structures pointed to by the lpServices parameter and MUST set the number of services returned in the lpServicesReturned parameter.

If the size of the lpServices array is insufficient for the list of services returned, the server MUST fail the call with ERROR_MORE_DATA (234) and return the size in bytes required in the pcbBytesNeeded parameter. If the size is sufficient for data returned, the server also returns the required size, in bytes.

If the size of the lpServices array is sufficient for the list of services returned, the enumerated data MAY be in the buffer in a non-contiguous manner, and portions of the lpServices array MAY be empty (filled with 0x00).

The server MUST use the process described in section 3.1.7, "Conversion Between ANSI and Unicode String Formats", to convert a string to the appropriate format.

The server MUST return the services in reverse sequence of the start order of the services.

The server MUST return ERROR_INVALID_PARAMETER (87) if a bitmask specified in dwServiceState contains undefined values.