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

Функция 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, содержащая имя файла журнала. Функция использует объекты производительности и счетчики, определенные в файле журнала, для расширения пути, указанного в параметре szWildCardPath .

Если значение РАВНО NULL, функция выполняет поиск на компьютере, указанном в szWildCardPath.

[in] szWildCardPath

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

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

[out] mszExpandedPathList

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

[in, out] pcchPathListLength

Размер буфера mszExpandedPathList в TCHAR. Если значение равно нулю для входных данных и объект существует, функция возвращает 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(экземпляр)\counter
  • \object\counter
Используйте звездочку (*) в качестве подстановочного знака, например \object(*)\counter.

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

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

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

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

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

Примечание

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

Требования

   
Минимальная версия клиента Windows XP [только классические приложения]
Минимальная версия сервера Windows Server 2003 [только классические приложения]
Целевая платформа Windows
Header pdh.h
Библиотека Pdh.lib
DLL Pdh.dll

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

PdhEnumObjectItems

PdhEnumObjects

PdhExpandCounterPath

PdhExpandWildCardPathH