Platform SDK: DLLs, Processes, and Threads

EnumServicesStatusEx

The EnumServicesStatusEx function enumerates services in the specified service control manager database. The name and status of each service are provided, along with additional data based on the specified information level.

This function supersedes the EnumServicesStatus function. It returns the same information EnumServicesStatus returns, plus the process identifier and additional flags for the service. In addition, EnumServicesStatusEx enables you to enumerate services that belong to a specified group.

BOOL EnumServicesStatusEx (
  SC_HANDLE hSCManager,       // handle to SCM database
  SC_ENUM_TYPE InfoLevel,     // information level
  DWORD dwServiceType,        // service type
  DWORD dwServiceState,       // service state
  LPBYTE lpServices,          // status buffer
  DWORD cbBufSize,            // size of status buffer
  LPDWORD pcbBytesNeeded,     // buffer size needed
  LPDWORD lpServicesReturned, // number of entries returned
  LPDWORD lpResumeHandle,     // next entry
  LPCTSTR pszGroupName        // load-order group name
);

Parameters

hSCManager

[in] Handle to the service control manager database. The OpenSCManager function returns this handle, which must have SC_MANAGER_ENUMERATE_SERVICE access.

InfoLevel

[in] Specifies which service attributes are to be returned. Use SC_ENUM_PROCESS_INFO to retrieve the name and service status information for each service in the database. The lpServices parameter is a pointer to a buffer that receives an array of ENUM_SERVICE_STATUS_PROCESS structures. The buffer must be large enough to hold the structures as well as the strings to which their members point.

Currently, no other information levels are defined.

dwServiceType

[in] Specifies the type of services to enumerate. This parameter can be one or more of the following values.

Value	Meaning
SERVICE_WIN32	Enumerates services of type SERVICE_WIN32_OWN_PROCESS and SERVICE_WIN32_SHARE_PROCESS.
SERVICE_DRIVER	Enumerates services of type SERVICE_KERNEL_DRIVER and SERVICE_FILE_SYSTEM_DRIVER.

dwServiceState

[in] Specifies the services to enumerate based on their state. This parameter can be one of the following values.

Value	Meaning
SERVICE_ACTIVE	Enumerates services that are in the following states: SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_RUNNING, SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDING, and SERVICE_PAUSED.
SERVICE_INACTIVE	Enumerates services that are in the SERVICE_STOPPED state.
SERVICE_STATE_ALL	Combines the SERVICE_ACTIVE and SERVICE_INACTIVE states.

lpServices

[out] Pointer to the buffer that receives the status information. The format of this data depends on the value of the InfoLevel parameter.

cbBufSize

[in] Specifies the size, in bytes, of the buffer pointed to by the lpServices parameter.

pcbBytesNeeded

[out] Pointer to a variable that receives the number of bytes needed to return the remaining service entries.

lpServicesReturned

[out] Pointer to a variable that receives the number of service entries returned.

lpResumeHandle

[in/out] Pointer to a variable that, on input, specifies the starting point of enumeration. You must set this value to zero the first time the EnumServicesStatusEx function is called. On output, this value is zero if the function succeeds. However, if the function returns zero and the GetLastError function returns ERROR_MORE_DATA, this value indicates the next service entry to be read when the EnumServicesStatusEx function is called to retrieve the additional data.

pszGroupName

[in] Specifies a load-order group name. If this parameter is a string, the only services enumerated are those that belong to the group that has the name specified by the string. If this parameter is an empty string, only services that do not belong to any group are enumerated. If this parameter is NULL, group membership is ignored and all services are enumerated.

Return Values

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. The following errors may be returned.

Error code	Meaning
ERROR_ACCESS_DENIED	The handle was not opened with SC_MANAGER_ENUMERATE_SERVICE access.
ERROR_MORE_DATA	The buffer is too small. Not all data in the active database could be returned. The pcbBytesNeeded parameter contains the number of bytes required to receive the remaining entries.
ERROR_INVALID_PARAMETER	An illegal parameter value was used.
ERROR_INVALID_HANDLE	The handle is invalid.
ERROR_INVALID_LEVEL	The InfoLevel parameter contains an unsupported value.
ERROR_SHUTDOWN_IN_PROGRESS	The system is shutting down; this function cannot be called.

Requirements

  Windows NT/2000: Requires Windows 2000.
  Header: Declared in Winsvc.h; include Windows.h.
  Library: Use Advapi32.lib.
  Unicode: Implemented as Unicode and ANSI versions on Windows 2000.

EnumServicesStatusEx

Parameters

Return Values

Requirements

See Also