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

Статья
03/08/2023

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

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

Синтаксис

PDH_FUNCTION PdhEnumObjectItemsA(
  [in]      LPCSTR  szDataSource,
  [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] szDataSource

Строка, завершающаяся значением NULL, указывающая имя файла журнала, используемого для перечисления имен счетчиков и экземпляров. Если значение РАВНО NULL, функция использует компьютер, указанный в

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

[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), а второй раз — для получения данных.

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

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

Примеры

Пример см. в разделе Перечисление объектов процесса.

Примечание

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

Требования

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

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

PdhEnumObjectItemsH

PdhEnumObjects

Share via