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

Статья
11/20/2024

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

Эта функция заменена функцией EnumServicesStatusEx. Он возвращает те же сведения, возвращается enumServicesStatus, а также идентификатор процесса и дополнительные сведения для службы. Кроме того, EnumServicesStatusEx позволяет перечислять службы, принадлежащие указанной группе.

Синтаксис

BOOL EnumServicesStatusA(
  [in]                SC_HANDLE              hSCManager,
  [in]                DWORD                  dwServiceType,
  [in]                DWORD                  dwServiceState,
  [out, optional]     LPENUM_SERVICE_STATUSA lpServices,
  [in]                DWORD                  cbBufSize,
  [out]               LPDWORD                pcbBytesNeeded,
  [out]               LPDWORD                lpServicesReturned,
  [in, out, optional] LPDWORD                lpResumeHandle
);

Параметры

[in] hSCManager

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

[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

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

Максимальный размер этого массива составляет 256 КБ. Чтобы определить требуемый размер, укажите значение NULL для этого параметра и 0 для параметра cbBufSize. Функция завершится ошибкой и GetLastError вернет ERROR_INSUFFICIENT_BUFFER. Параметр 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

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

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

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

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

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

Возвращаемый код	Описание
ERROR_ACCESS_DENIED	Дескриптор не имеет права доступа SC_MANAGER_ENUMERATE_SERVICE.
ERROR_INVALID_HANDLE	Указанный дескриптор недопустим.
ERROR_INVALID_PARAMETER	Указанный параметр недопустим.
ERROR_MORE_DATA	Существует больше записей служб, чем в буфере lpServices. Фактическое количество записей службы, записанных в lpServices, возвращается в параметре lpServicesReturned. Количество байтов, необходимых для получения оставшихся записей, возвращается в параметре pcbBytesNeed. Остальные службы можно перечислить с помощью дополнительных вызовов EnumServicesStatus с параметром lpResumeHandle, указывающим следующую службу для чтения.

Замечания

Заметка

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

Требования

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