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

Статья
11/20/2024

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

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

Синтаксис

PDH_FUNCTION PdhEnumMachinesA(
  [in]      LPCSTR  szDataSource,
  [out]     PZZSTR  mszMachineList,
  [in, out] LPDWORD pcchBufferSize
);

Параметры

[in] szDataSource

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

[out] mszMachineList

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

[in, out] pcchBufferSize

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

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

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

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

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

Возвращаемый код

Описание

PDH_MORE_DATA

Буфер mszMachineNameList слишком мал, чтобы содержать все данные. Это возвращаемое значение ожидается, если pcchBufferLength равно нулю входных данных. Если указанный размер входных данных больше нуля, но меньше требуемого размера, не следует полагаться на возвращаемый размер, чтобы перераспределить буфер.

PDH_INVALID_ARGUMENT

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

Замечания

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

Заметка

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

Требования

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

См. также

PdhConnectMachine

PdhEnumMachinesH

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