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

Статья
11/20/2024

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

Эта функция идентична PdhEnumObjects, за исключением того, что она поддерживает использование дескрипторов в источниках данных.

Синтаксис

PDH_FUNCTION PdhEnumObjectsHA(
  [in]      PDH_HLOG hDataSource,
  [in]      LPCSTR   szMachineName,
  [out]     PZZSTR   mszObjectList,
  [in, out] LPDWORD  pcchBufferSize,
  [in]      DWORD    dwDetailLevel,
  [in]      BOOL     bRefresh
);

Параметры

[in] hDataSource

Обработка источника данных, возвращаемого функцией PdhBindInputDataSource.

[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 определяет PdhEnumObjectsH как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

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

См. также

PdhBindInputDataSource

PdhEnumObjectItemsH

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