Функция PdhEnumObjectItemsA (pdh.h)
Возвращает имена счетчиков и экземпляров указанного объекта, которые существуют на указанном компьютере или в указанном файле журнала.
Чтобы использовать дескрипторы для источников данных, используйте функцию 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
Уровень детализации возвращаемых элементов производительности. Будут возвращены все элементы, которые имеют указанный уровень детализации или меньше (уровни перечислены в порядке увеличения). Этот параметр может принимать одно из указанных ниже значений.
[in] dwFlags
Этот параметр должен быть равен нулю.
Возвращаемое значение
Если функция выполняется успешно, она возвращает ERROR_SUCCESS.
Если функция завершается ошибкой, возвращаемым значением является системный код ошибки или код ошибки PDH. Ниже приведены возможные значения.
| Код возврата | Описание |
|---|---|
|
Один из буферов слишком мал, чтобы содержать список имен. Это возвращаемое значение ожидается, если pcchCounterListLength или pcchInstanceListLength равно нулю при входе. Если указанный размер входных данных больше нуля, но меньше требуемого размера, не следует полагаться на возвращаемый размер для перераспределения буфера. |
|
Недействительный параметр. Например, в некоторых выпусках эта ошибка может возникнуть, если указанный размер входных данных больше нуля, но меньше требуемого размера. |
|
Не удалось выделить память для поддержки этой функции. |
|
Указанный компьютер находится в автономном режиме или недоступен. |
|
Не удалось найти указанный объект на указанном компьютере или в указанном файле журнала. |
Комментарии
Эту функцию следует вызывать дважды: первый раз, чтобы получить требуемый размер буфера (задайте для буферов значение 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 |