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

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

  • Статья

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

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

Синтаксис

PDH_FUNCTION PdhExpandWildCardPathA(
  [in]      LPCSTR  szDataSource,
  [in]      LPCSTR  szWildCardPath,
  [out]     PZZSTR  mszExpandedPathList,
  [in, out] LPDWORD pcchPathListLength,
  [in]      DWORD   dwFlags
);

Параметры

[in] szDataSource

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

Если NULL, функция выполняет поиск компьютера, указанного в szWildCardPath.

[in] szWildCardPath

строке со значением NULL-terminated, указывающей путь счетчика для расширения. Максимальная длина пути счетчика составляет PDH_MAX_COUNTER_PATH.

Если параметр szDataSourceNULL, функция выполняет поиск компьютера, указанного в пути к совпадениям. Если путь не указывает компьютер, функция выполняет поиск локального компьютера.

[out] mszExpandedPathList

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

[in, out] pcchPathListLength

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

Примечание Необходимо добавить его к требуемому размеру в Windows XP.
 

[in] dwFlags

Флаги, указывающие, какие подстановочные знаки не развертываются. Можно указать один или несколько флагов.

Ценность Значение
PDH_NOEXPANDCOUNTERS
 Не разверните имя счетчика, если путь содержит подстановочный знак для имени счетчика.
PDH_NOEXPANDINSTANCES
 Не разверните имя экземпляра, если путь содержит подстановочный знак для родительского экземпляра, имени экземпляра или индекса экземпляра.
PDH_REFRESHCOUNTERS
 Обновите список счетчиков.

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

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

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

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

Замечания

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

PdhExpandWildCardPath отличается от PdhExpandCounterPath следующим образом:

  1. Позволяет управлять расширением подстановочных знаков.
  2. Содержимое файла журнала можно использовать в качестве источника имен счетчиков.
Общий формат пути счетчика выглядит следующим образом:

\computer\object(parent/instance#index)\counter

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

Ниже приведен список возможных форматов:

  • \\computer\object(parent/instance#index)\counter
  • \\computer\object(parent/instance)\counter
  • \\computer\object(instance#index)\counter
  • \\computer\object(instance)\counter
  • \\computer\object\counter
  • \object(parent/instance#index)\counter
  • \object(parent/instance)\counter
  • \object(instance#index)\counter
  • \object(instance)\counter
  • \object\counter
Используйте звездочку (*) в качестве подстановочного знака, например \object(*)\counter.

Если в родительском имени указан подстановочный знак, будут возвращены все экземпляры указанного объекта, соответствующие указанному экземпляру и полям счетчика. Например, \object(*/instance)\counter.

Если в имени экземпляра указан подстановочный знак, все экземпляры указанного объекта и родительского объекта будут возвращены, если все имена экземпляров, соответствующие указанному индексу, соответствуют подстановочным знакам. Например, \object(parent/*)\counter. Если объект не содержит экземпляр, возникает ошибка.

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

Поддерживаются совпадения строк частичных путей счетчика (например, "pro*").

до Windows Vista: совпадения с частичными подстановочными знаками не поддерживаются.

Заметка

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

Требования

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

См. также

PdhEnumObjectItems

PdhEnumObjects

PdhExpandCounterPath

PdhExpandWildCardPathH