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

Статья
08/25/2023

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

Синтаксис

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

Параметры

[in] szMachineName

Строка, завершающаяся значением NULL, указывающая имя компьютера, на котором находится указанный объект производительности или счетчик. Имя компьютера можно указать с помощью 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 [только классические приложения]
Целевая платформа	Windows
Header	pdh.h
Библиотека	Pdh.lib
DLL	Pdh.dll

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

PdhLookupPerfIndexByName

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