Функция PdhExpandCounterPathA (pdh.h)
Проверяет указанный компьютер (или локальный компьютер, если он не указан) для счетчиков и экземпляров счетчиков, которые соответствуют строкам подстановочных знаков в пути счетчика.
Синтаксис
PDH_FUNCTION PdhExpandCounterPathA(
[in] LPCSTR szWildCardPath,
[out] PZZSTR mszExpandedPathList,
[in, out] LPDWORD pcchPathListLength
);
Параметры
[in] szWildCardPath
строке null-terminated, содержащей путь счетчика для расширения. Функция выполняет поиск компьютера, указанного в пути к совпадениям. Если путь не указывает компьютер, функция выполняет поиск локального компьютера. Максимальная длина пути счетчика составляет PDH_MAX_COUNTER_PATH.
[out] mszExpandedPathList
Выделенный вызывающим буфером, который получает список развернутых путей счетчика, которые соответствуют спецификации подстановочных знаков в szWildCardPath. Каждый путь счетчика в этом списке завершается символом null. Список завершается двумя символами NULL. Установите значение NULL, если pcchPathListLength равно нулю.
[in, out] pcchPathListLength
Размер буфера mszExpandedPathList
Возвращаемое значение
Если функция выполнена успешно, она возвращает ERROR_SUCCESS.
Если функция завершается ошибкой, возвращаемое значение представляет собой код ошибки системы или код ошибки PDH.
| Возвращаемый код | Описание |
|---|---|
|
Буфер mszExpandedPathList слишком мал, чтобы содержать список путей. Это возвращаемое значение ожидается, если pcchPathListLength равно нулю входных данных. Если указанный размер входных данных больше нуля, но меньше требуемого размера, не следует полагаться на возвращаемый размер, чтобы перераспределить буфер. |
|
Недопустимый параметр. Например, в некоторых выпусках можно получить эту ошибку, если указанный размер входных данных больше нуля, но меньше требуемого размера. |
|
Не удалось выделить память для поддержки этой функции. |
Замечания
Эта функция должна вызываться дважды, при первом получении требуемого размера буфера (присвойте 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 [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | pdh.h |
| библиотеки |
Pdh.lib |
| DLL | Pdh.dll |