Функция EnumServicesStatusExA (winsvc.h)

Статья
11/20/2024

Перечисляет службы в указанной базе данных диспетчера управления службами. Имя и состояние каждой службы предоставляются вместе с дополнительными данными на основе указанного уровня информации.

Синтаксис

BOOL EnumServicesStatusExA(
  [in]                SC_HANDLE    hSCManager,
  [in]                SC_ENUM_TYPE InfoLevel,
  [in]                DWORD        dwServiceType,
  [in]                DWORD        dwServiceState,
  [out, optional]     LPBYTE       lpServices,
  [in]                DWORD        cbBufSize,
  [out]               LPDWORD      pcbBytesNeeded,
  [out]               LPDWORD      lpServicesReturned,
  [in, out, optional] LPDWORD      lpResumeHandle,
  [in, optional]      LPCSTR       pszGroupName
);

Параметры

[in] hSCManager

Дескриптор базы данных диспетчера управления службами. Этот дескриптор возвращается функцией OpenSCManager и должен иметь право SC_MANAGER_ENUMERATE_SERVICE доступа. Дополнительные сведения см. в службы безопасности и доступа.

[in] InfoLevel

Возвращаемые атрибуты службы. Используйте SC_ENUM_PROCESS_INFO для получения сведений о имени и состоянии службы для каждой службы в базе данных. Параметр lpServices — это указатель на буфер, который получает массив ENUM_SERVICE_STATUS_PROCESS структур. Буфер должен быть достаточно большим, чтобы хранить структуры, а также строки, к которым указывают их члены.

В настоящее время никакие другие уровни информации не определены.

[in] dwServiceType

Тип служб, которые необходимо перечислить. Этот параметр может быть одним или несколькими из следующих значений.

Ценность	Значение
SERVICE_DRIVER 0x0000000B	Службы типа SERVICE_KERNEL_DRIVER и SERVICE_FILE_SYSTEM_DRIVER.
SERVICE_FILE_SYSTEM_DRIVER 0x00000002	Службы драйверов файловой системы.
SERVICE_KERNEL_DRIVER 0x00000001	Службы драйверов.
SERVICE_WIN32 0x00000030	Службы типа SERVICE_WIN32_OWN_PROCESS и SERVICE_WIN32_SHARE_PROCESS.
SERVICE_WIN32_OWN_PROCESS 0x00000010	Службы, которые выполняются в своих собственных процессах.
SERVICE_WIN32_SHARE_PROCESS 0x00000020	Службы, которые совместно используют процесс с одной или несколькими другими службами. Дополнительные сведения см. в программ службы.

[in] dwServiceState

Состояние перечисления служб. Этот параметр может быть одним из следующих значений.

Ценность	Значение
SERVICE_ACTIVE 0x00000001	Перечисляет службы, которые находятся в следующих состояниях: SERVICE_START_PENDING, SERVICE_STOP_PENDING, SERVICE_RUNNING, SERVICE_CONTINUE_PENDING, SERVICE_PAUSE_PENDINGи SERVICE_PAUSED.
SERVICE_INACTIVE 0x00000002	Перечисляет службы, которые находятся в состоянии SERVICE_STOPPED.
SERVICE_STATE_ALL 0x00000003	Объединяет состояния SERVICE_ACTIVE и SERVICE_INACTIVE.

[out, optional] lpServices

Указатель на буфер, получающий сведения о состоянии. Формат этих данных зависит от значения параметра InfoLevel.

Максимальный размер этого массива составляет 256 КБ. Чтобы определить требуемый размер, укажите NULL для этого параметра и 0 для параметра cbBufSize. Функция завершится ошибкой, и GetLastError вернет ERROR_MORE_DATA. Параметр pcbBytesNeed получит необходимый размер.

Windows Server 2003 и Windows XP: максимальный размер этого массива составляет 64 КБ. Это ограничение было увеличено по состоянию на Windows Server 2003 с пакетом обновления 1 (SP1) и Windows XP с пакетом обновления 2 (SP2).

[in] cbBufSize

Размер буфера, на который указывает параметр lpServices в байтах.

[out] pcbBytesNeeded

Указатель на переменную, которая получает количество байтов, необходимых для возврата оставшихся записей службы, если буфер слишком мал.

[out] lpServicesReturned

Указатель на переменную, которая получает количество возвращаемых записей службы.

[in, out, optional] lpResumeHandle

Указатель на переменную, указывающую начальную точку перечисления. Это значение должно быть равно нулю при первом вызове функции enumServicesStatusEx. В выходных данных это значение равно нулю, если функция завершается успешно. Однако если функция возвращает ноль , а функция GetLastError возвращает ERROR_MORE_DATA, это значение указывает, что следующая запись службы будет считываться при вызове функции EnumServicesStatusEx для получения дополнительных данных.

[in, optional] pszGroupName

Имя группы заказа нагрузки. Если этот параметр является строкой, перечислимые только службы, принадлежащие группе, которая имеет имя, указанное строкой. Если этот параметр является пустой строкой, перечисляются только службы, которые не относятся к какой-либо группе. Если этот параметр NULL, членство в группах игнорируется и перечисляются все службы.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение ненулевое.

Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError. Могут быть возвращены следующие ошибки.

Возвращаемый код	Описание
ERROR_ACCESS_DENIED	Дескриптор не имеет права доступа SC_MANAGER_ENUMERATE_SERVICE.
ERROR_MORE_DATA	Буфер слишком мал. Не все данные в активной базе данных могут быть возвращены. Параметр pcbBytesNeeded содержит количество байтов, необходимых для получения оставшихся записей.
ERROR_INVALID_PARAMETER	Использовалось недопустимое значение параметра.
ERROR_INVALID_HANDLE	Дескриптор недопустим.
ERROR_INVALID_LEVEL	Параметр InfoLevel содержит неподдерживаемое значение.
ERROR_SHUTDOWN_IN_PROGRESS	Система завершает работу; эту функцию нельзя вызвать.

Замечания

Если вызывающий объект не имеет права SERVICE_QUERY_STATUS доступа к службе, служба автоматически опущена из списка служб, возвращенных клиенту.

Заметка

Заголовок winsvc.h определяет EnumServicesStatusEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	winsvc.h (включая Windows.h)
библиотеки	Advapi32.lib
DLL	Advapi32.dll

См. также

ENUM_SERVICE_STATUS_PROCESS

Функции службы

установка, удаление и перечисление служб

Поделиться через