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

Статья
11/20/2024

Возвращает имя объекта производительности или имя счетчика, соответствующее указанному индексу.

Синтаксис

PDH_FUNCTION PdhLookupPerfNameByIndexA(
  [in]      LPCSTR  szMachineName,
  [in]      DWORD   dwNameIndex,
  [out]     LPSTR   szNameBuffer,
  [in, out] LPDWORD pcchNameBufferSize
);

Параметры

[in] szMachineName

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

[in] dwNameIndex

Индекс объекта производительности или счетчика.

[out] szNameBuffer

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

[in, out] pcchNameBufferSize

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

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

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

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

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

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

Описание

PDH_MORE_DATA

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

PDH_INVALID_ARGUMENT

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

Замечания

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

Windows XP: Необходимо указать размер буфера и буфера. Наборы функций pcchNameBufferSize в требуемый размер или размер используемого буфера. Если буфер слишком мал, функция возвращает PDH_INSUFFICIENT_BUFFER вместо PDH_MORE_DATA. Максимальный размер строки в байтах — PDH_MAX_COUNTER_NAME * sizeof(TCHAR).

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

HKEY_LOCAL_MACHINE
   \SOFTWARE
      \Microsoft
         \Windows NT
            \CurrentVersion
               \Perflib
                  Last Counter = highest counter index
                  Last Help = highest help index
                  \009
                     Counters = 2 System 4 Memory...
                     Help = 3 The System Object Type...
                  \supported language, other than English
                     Counters = ...
                     Help = ...

Заметка

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

Требования

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

См. также

PdhLookupPerfIndexByName

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