Share via

3.1.4.39 REnumServicesStatusExA (Opnum 41)

  • Article

The REnumServicesStatusExA method enumerates services in the specified SCM database, based on the specified information level.

 DWORD REnumServicesStatusExA(
   [in] SC_RPC_HANDLE hSCManager,
   [in] SC_ENUM_TYPE InfoLevel,
   [in] DWORD dwServiceType,
   [in] DWORD dwServiceState,
   [out, size_is(cbBufSize)] LPBYTE lpBuffer,
   [in, range(0, 1024 * 256)] DWORD cbBufSize,
   [out] LPBOUNDED_DWORD_256K pcbBytesNeeded,
   [out] LPBOUNDED_DWORD_256K lpServicesReturned,
   [in, out, unique] LPBOUNDED_DWORD_256K lpResumeIndex,
   [in, string, unique, range(0, SC_MAX_NAME_LENGTH)] 
     LPCSTR pszGroupName
 );

hSCManager: An SC_RPC_HANDLE (section 2.2.4) data type that defines the handle to the SCM database 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.

InfoLevel: An SC_ENUM_TYPE (section 2.2.20) structure that specifies which service attributes to return. MUST be SC_ENUM_PROCESS_INFO.

dwServiceType: A value that specifies what type of service records to enumerate. This MUST be one or a combination of the following values.

Value

Meaning

SERVICE_KERNEL_DRIVER

0x0000000F

Enumerates services of type SERVICE_KERNEL_DRIVER.

SERVICE_FILE_SYSTEM_DRIVER

0x00000002

Enumerates services of type SERVICE_FILE_SYSTEM_DRIVER.

SERVICE_WIN32_OWN_PROCESS

0x00000010

Enumerates services of type SERVICE_WIN32_OWN_PROCESS.

SERVICE_WIN32_SHARE_PROCESS

0x00000020

Enumerates services of type SERVICE_WIN32_SHARE_PROCESS.

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

Value

Meaning

SERVICE_ACTIVE

0x00000001

Enumerates service records with ServiceStatus.dwCurrentState values from 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 with the ServiceStatus.dwCurrentState value SERVICE_STOPPED.

SERVICE_STATE_ALL

0x00000003

Enumerates service records with ServiceStatus.dwCurrentState values from the following: SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_RUNNING, SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING, SERVICE_PAUSED, and SERVICE_STOPPED.

lpBuffer: A pointer to the buffer that contains the status information in the form of an array of ENUM_SERVICE_STATUS_PROCESSA (section 2.2.12) structures.

cbBufSize: The size, in bytes, of the buffer pointed to by lpBuffer.

pcbBytesNeeded: An LPBOUNDED_DWORD_256K (section 2.2.9) pointer to a variable that contains the number of bytes needed to return the configuration information.

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

lpResumeIndex: An LPBOUNDED_DWORD_256K (section 2.2.9) pointer to a variable that contains the current index in the enumerated list of service entries. The server MUST assign a unique number to each service for the boot session, in increasing order, and increment that number by one for each service addition. The value of the lpResumeIndex parameter is one of these numbers, which the server can use to determine the resumption point for the enumeration.

pszGroupName: A pointer to a string that specifies service records to enumerate based on their ServiceGroup values.

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.

6

ERROR_INVALID_HANDLE

The handle is no longer valid.

87

ERROR_INVALID_PARAMETER

A parameter that was specified is invalid.

124

ERROR_INVALID_LEVEL

The InfoLevel parameter contains an unsupported value.

234

ERROR_MORE_DATA

More data is available.

1060

ERROR_SERVICE_DOES_NOT_EXIST

The group specified by the pszGroupName parameter does not exist in the SCM GroupList.

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 in the SCM database identified by the hSCManager parameter with the ServiceGroup value matching the pszGroupName parameter, the ServiceStatus.dwCurrentState equal to the state specified by dwServiceState, and the Type equal to dwServiceType of the client request. The server MUST return this list by setting the service name, display name, and appropriate configuration data for each of the services in the list in the array of ENUM_SERVICE_STATUS_PROCESSA (section 2.2.12) structures pointed to by the lpBuffer parameter and MUST set the number of services returned in the lpServicesReturned parameter.

If the lpResumeIndex value is not zero, the server MUST use that as the offset to the service list and return only services starting at this offset. If the lpResumeIndex value is zero, the server MUST return all services. The server MUST set this parameter to zero if the operation succeeds. If the lpResumeIndex value is set by the client to any nonzero number not returned by the server, the behavior is not defined.

If the pszGroupName parameter is a nonempty or non-NULL string, the server MUST enumerate only the services that belong to the group whose name is specified by the pszGroupName parameter. If the pszGroupName parameter is an empty string, the server MUST enumerate only the services that do not belong to any group. If the pszGroupName parameter is NULL, the server MUST ignore the group membership and enumerate all services.

If the size of the lpBuffer 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 lpBuffer 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 lpBuffer array MAY be empty.

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

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

The server MUST return ERROR_INVALID_PARAMETER (87) if a bitmask specified in dwServiceType is zero or contains undefined values.