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

Статья
08/25/2023

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

Примечание Эта функция заменена функцией PdhExpandWildCardPath .

Синтаксис

PDH_FUNCTION PdhExpandCounterPathA(
  [in]      LPCSTR  szWildCardPath,
  [out]     PZZSTR  mszExpandedPathList,
  [in, out] LPDWORD pcchPathListLength
);

Параметры

[in] szWildCardPath

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

[out] mszExpandedPathList

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

[in, out] pcchPathListLength

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

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

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

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

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

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

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

Общий формат пути счетчика выглядит следующим образом:

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

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

Пути счетчиков, которые необходимо использовать, определяются самим счетчиком. Например, объект LogicalDisk имеет индекс экземпляра, поэтому необходимо указать #index или подстановочный знак. Поэтому можно использовать следующий формат:

\LogicalDisk(/#*)*

Для сравнения, объекту Process не требуется индекс экземпляра. Поэтому можно использовать следующий формат:

\Process(*)\ID Process

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

\\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

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

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

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

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

Примеры

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


#include <windows.h>
#include <stdio.h>
#include <stdlib.h>
#include <pdh.h>
#include <pdhmsg.h>

#pragma comment(lib, "pdh.lib")

CONST PWSTR WILDCARD_PATH = L"\\Processor(*)\\*";

void wmain(void)
{
    PDH_STATUS Status;
    PWSTR EndOfPaths;
    PWSTR Paths = NULL;
    DWORD BufferSize = 0;

    Status = PdhExpandCounterPath(WILDCARD_PATH, Paths, &BufferSize);

    while (Status == PDH_MORE_DATA) 
    {
        Paths = (PWSTR)malloc(BufferSize * sizeof(WCHAR));
        Status = PdhExpandCounterPath(WILDCARD_PATH, Paths, &BufferSize);
    }

    if (Status != ERROR_SUCCESS) 
    {
        wprintf(L"\nPdhExpandCounterPath failed with status 0x%x", Status);
        goto Cleanup;
    }

    if (Paths == NULL) 
    {
        wprintf(L"\nThe counter path %s cannot be expanded.", WILDCARD_PATH);
        goto Cleanup;
    }

    EndOfPaths = Paths + BufferSize;

    // On Vista and later operating systems, the buffer is terminated with two 
    // null-terminator characters; however, on earlier systems, the buffer is
    // not terminated with two null-terminator characters. This covers both cases.
    for (PWSTR p = Paths; ((p != EndOfPaths) && (*p != L'\0')); p += wcslen(p) + 1) 
    {
        wprintf(L"\n%s", p);
    }

Cleanup:
    if (Paths) 
    {
        free(Paths);
    }
}

Примечание

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

Требования

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

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

PdhExpandWildCardPath

PdhMakeCounterPath

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