Функция PdhEnumObjectsA (pdh.h)

Статья
11/20/2024

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

Чтобы использовать дескриптор для источников данных, используйте функцию PdhEnumObjectsH.

Синтаксис

PDH_FUNCTION PdhEnumObjectsA(
  [in]      LPCSTR  szDataSource,
  [in]      LPCSTR  szMachineName,
  [out]     PZZSTR  mszObjectList,
  [in, out] LPDWORD pcchBufferSize,
  [in]      DWORD   dwDetailLevel,
  [in]      BOOL    bRefresh
);

Параметры

[in] szDataSource

строка null-terminated, указывающая имя файла журнала, используемого для перечисления объектов производительности. Если null, функция использует компьютер, указанный в

параметр szMachineName для перечисления имен.

[in] szMachineName

строка, завершающаясяnull, указывающая имя компьютера, используемого для перечисления объектов производительности.

Включите ведущие косые черты в имя компьютера, например \computername.

Если параметр szDataSourceNULL, можно задать szMachineName значение null, чтобы указать локальный компьютер.

[out] mszObjectList

Выделенный вызывающим буфером, который получает список имен объектов. Каждое имя объекта в этом списке завершается символом null. Список завершается двумя символами null-terminator. Установите значение NULL, если параметр pcchBufferLength равен нулю.

[in, out] pcchBufferSize

Размер буфера mszObjectList в TCHARs. Если значение равно нулю входных данных, функция возвращает PDH_MORE_DATA и задает этот параметр требуемому размеру буфера. Если буфер больше требуемого размера, функция задает этот параметр фактическому размеру используемого буфера. Если указанный размер входных данных больше нуля, но меньше требуемого размера, не следует полагаться на возвращаемый размер, чтобы перераспределить буфер.

Windows XP: Добавить один к требуемому размеру буфера.

[in] dwDetailLevel

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

Ценность	Значение
PERF_DETAIL_NOVICE	Уровень детализации новичков.
PERF_DETAIL_ADVANCED	Расширенный уровень детализации пользователя.
PERF_DETAIL_EXPERT	Уровень детализации эксперта.
PERF_DETAIL_WIZARD	Уровень детализации системного конструктора.

[in] bRefresh

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

Если вы вызываете эту функцию дважды, один раз, чтобы получить размер списка и второй раз, чтобы получить фактический список, задайте для этого параметра значение TRUE при первом вызове и FALSE во втором вызове. Если оба вызова TRUE, второй вызов также может возвращать PDH_MORE_DATA, так как данные объекта могут измениться между вызовами.

Ценность	Значение
TRUE	Кэш объектов автоматически обновляется перед возвратом объектов.
FALSE	Не обновляйте кэш автоматически.

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

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

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

Возвращаемый код	Описание
PDH_MORE_DATA	Буфер mszObjectList слишком мал для хранения списка объектов. Это возвращаемое значение ожидается, если pcchBufferLength равно нулю входных данных. Если указанный размер входных данных больше нуля, но меньше требуемого размера, не следует полагаться на возвращаемый размер, чтобы перераспределить буфер.
PDH_CSTATUS_NO_MACHINE	Указанный компьютер находится в автономном режиме или недоступен.
PDH_CSTATUS_NO_OBJECT	Не удалось найти указанный объект.
PDH_INVALID_ARGUMENT	Недопустимый параметр. Например, в некоторых выпусках можно получить эту ошибку, если указанный размер входных данных больше нуля, но меньше требуемого размера.

Замечания

Эту функцию следует вызывать дважды, при первом получении требуемого размера буфера (задайте mszObjectList значение NULL и pcchBufferLength 0) и второй раз, чтобы получить данные.

Заметка

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

Требования

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

См. также

PdhEnumObjectItems

PdhEnumObjectsH

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