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

Статья
08/25/2023

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

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

Синтаксис

PDH_FUNCTION PdhEnumObjectItemsHA(
  [in]      PDH_HLOG hDataSource,
  [in]      LPCSTR   szMachineName,
  [in]      LPCSTR   szObjectName,
  [out]     PZZSTR   mszCounterList,
  [in, out] LPDWORD  pcchCounterListLength,
  [out]     PZZSTR   mszInstanceList,
  [in, out] LPDWORD  pcchInstanceListLength,
  [in]      DWORD    dwDetailLevel,
  [in]      DWORD    dwFlags
);

Параметры

[in] hDataSource

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

[in] szMachineName

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

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

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

[in] szObjectName

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

[out] mszCounterList

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

[in, out] pcchCounterListLength

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

[out] mszInstanceList

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

[in, out] pcchInstanceListLength

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

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

[in] dwDetailLevel

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

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

[in] dwFlags

Этот параметр должен быть равен нулю.

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

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

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

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

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

Последовательные вызовы этой функции возвращают одинаковые списки счетчиков и экземпляров, так как PdhEnumObjectItemsH всегда запрашивает список объектов производительности, определенный последним вызовом PdhEnumObjectsH или PdhEnumObjectItemsH. Чтобы обновить список объектов производительности, вызовите PdhEnumObjectsH со значением флага bRefreshTRUE , прежде чем снова вызывать PdhEnumObjectItemsH .

Порядок имен экземпляров и счетчиков не определен.

Примечание

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

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	pdh.h
Библиотека	Pdh.lib
DLL	Pdh.dll

См. также раздел

PdhBindInputDataSource

PdhEnumObjectsH

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