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

Статья
11/20/2024

Добавляет указанный счетчик в запрос.

Синтаксис

PDH_FUNCTION PdhAddCounterA(
  [in]  PDH_HQUERY   hQuery,
  [in]  LPCSTR       szFullCounterPath,
  [in]  DWORD_PTR    dwUserData,
  [out] PDH_HCOUNTER *phCounter
);

Параметры

[in] hQuery

Обработайте запрос, к которому требуется добавить счетчик. Этот дескриптор возвращается функцией PdhOpenQuery.

[in] szFullCounterPath

Строка, завершающая значение NULL, содержащая путь счетчика. Дополнительные сведения о формате пути счетчика см. в разделе Указание пути счетчика. Максимальная длина пути счетчика составляет PDH_MAX_COUNTER_PATH.

[in] dwUserData

Определяемое пользователем значение. Это значение становится частью сведений о счетчике. Чтобы получить это значение позже, вызовите функцию PdhGetCounterInfo и перейдите к элементу dwUserData структуры PDH_COUNTER_INFO.

[out] phCounter

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

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

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

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

Возвращаемый код	Описание
PDH_CSTATUS_BAD_COUNTERNAME	Путь счетчика не может быть проанализирован или интерпретирован.
PDH_CSTATUS_NO_COUNTER	Не удалось найти указанный счетчик на компьютере или в файле журнала.
PDH_CSTATUS_NO_COUNTERNAME	Путь счетчика пуст.
PDH_CSTATUS_NO_MACHINE	Путь не содержал имени компьютера, и функция не смогла получить имя локального компьютера.
PDH_CSTATUS_NO_OBJECT	Не удалось найти указанный объект на компьютере или в файле журнала.
PDH_FUNCTION_NOT_FOUND	Не удалось определить функцию вычисления, используемую для этого счетчика.
PDH_INVALID_ARGUMENT	Один или несколько аргументов недопустимы.
PDH_INVALID_HANDLE	Недопустимый дескриптор запроса.
PDH_MEMORY_ALLOCATION_FAILURE	Не удалось выделить память, необходимую для выполнения функции.

Замечания

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

Если экземпляр счетчика указан, который еще не существует, PdhAddCounter не сообщает об ошибке. Вместо этого он возвращает ERROR_SUCCESS. Причина этого поведения заключается в том, что неизвестно, был ли указан существующий экземпляр счетчика или будет ли он существовать, но еще не создан.

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

Примеры

Пример см. в разделе счетчиков производительности или чтения данных о производительности из файла журнала.

Заметка

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

Требования

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