Функция PdhGetFormattedCounterArrayW (pdh.h)
Возвращает массив отформатированных значений счетчиков. Используйте эту функцию, если требуется отформатировать значения счетчика счетчика, содержащего подстановочный знак для имени экземпляра.
Синтаксис
PDH_FUNCTION PdhGetFormattedCounterArrayW(
[in] PDH_HCOUNTER hCounter,
[in] DWORD dwFormat,
[in, out] LPDWORD lpdwBufferSize,
[out] LPDWORD lpdwItemCount,
[out] PPDH_FMT_COUNTERVALUE_ITEM_W ItemBuffer
);
Параметры
[in] hCounter
Обработайте счетчик, текущее значение которого требуется отформатировать. Функция PdhAddCounter возвращает этот дескриптор.
[in] dwFormat
Определяет тип данных отформатированного значения. Укажите одно из следующих значений.
Для объединения типа данных с одним из следующих факторов масштабирования можно использовать побитовый оператор OR (|).
[in, out] lpdwBufferSize
Размер буфера ItemBuffer в байтах. Если значение равно нулю входных данных, функция возвращает PDH_MORE_DATA и задает этот параметр требуемому размеру буфера. Если буфер больше требуемого размера, функция задает этот параметр фактическому размеру используемого буфера. Если указанный размер входных данных больше нуля, но меньше требуемого размера, не следует полагаться на возвращаемый размер, чтобы перераспределить буфер.
[out] lpdwItemCount
Число значений счетчиков в буфере
[out] ItemBuffer
Выделенный вызывающим буфером, получающий массив PDH_FMT_COUNTERVALUE_ITEM структур; структуры содержат значения счетчиков. Установите значение NULL, если lpdwBufferSize равно нулю.
Возвращаемое значение
Если функция выполнена успешно, она возвращает ERROR_SUCCESS.
Если функция завершается ошибкой, возвращаемое значение представляет собой код ошибки системы или код ошибки PDH. Ниже приведены возможные значения.
| Возвращаемый код | Описание |
|---|---|
|
Буфер |
|
Недопустимый параметр или неправильно отформатирован. Например, в некоторых выпусках можно получить эту ошибку, если указанный размер входных данных больше нуля, но меньше требуемого размера. |
|
Недопустимый дескриптор счетчика. |
Замечания
Эта функция должна вызываться дважды, при первом получении требуемого размера буфера (присвойте ItemBuffer значение NULL и lpdwBufferSize значение 0), а также во второй раз, чтобы получить данные.
Данные для счетчика блокируются на время вызова PdhGetFormattedCounterArra y, чтобы предотвратить любые изменения во время обработки вызова.
Примеры
В следующем примере показано, как использовать эту функцию.
#include <windows.h>
#include <stdio.h>
#include <pdh.h>
#include <pdhmsg.h>
#pragma comment(lib, "pdh.lib")
CONST PWSTR COUNTER_PATH = L"\\Processor(*)\\% Processor Time";
CONST ULONG SAMPLE_INTERVAL_MS = 1000;
void main()
{
PDH_HQUERY hQuery = NULL;
PDH_STATUS status = ERROR_SUCCESS;
PDH_HCOUNTER hCounter = NULL;
DWORD dwBufferSize = 0; // Size of the pItems buffer
DWORD dwItemCount = 0; // Number of items in the pItems buffer
PDH_FMT_COUNTERVALUE_ITEM *pItems = NULL; // Array of PDH_FMT_COUNTERVALUE_ITEM structures
if (status = PdhOpenQuery(NULL, 0, &hQuery))
{
wprintf(L"PdhOpenQuery failed with 0x%x.\n", status);
goto cleanup;
}
// Specify a counter object with a wildcard for the instance.
if (status = PdhAddCounter(hQuery, COUNTER_PATH, 0, &hCounter))
{
wprintf(L"PdhAddCounter failed with 0x%x.\n", status);
goto cleanup;
}
// Some counters need two sample in order to format a value, so
// make this call to get the first value before entering the loop.
if (status = PdhCollectQueryData(hQuery))
{
wprintf(L"PdhCollectQueryData failed with 0x%x.\n", status);
goto cleanup;
}
for (int i = 0; i < 10; i++)
{
Sleep(SAMPLE_INTERVAL_MS);
if (status = PdhCollectQueryData(hQuery))
{
wprintf(L"PdhCollectQueryData failed with 0x%x.\n", status);
goto cleanup;
}
// Get the required size of the pItems buffer.
status = PdhGetFormattedCounterArray(hCounter, PDH_FMT_DOUBLE, &dwBufferSize, &dwItemCount, pItems);
if (PDH_MORE_DATA == status)
{
pItems = (PDH_FMT_COUNTERVALUE_ITEM *) malloc(dwBufferSize);
if (pItems)
{
status = PdhGetFormattedCounterArray(hCounter, PDH_FMT_DOUBLE, &dwBufferSize, &dwItemCount, pItems);
if (ERROR_SUCCESS == status)
{
// Loop through the array and print the instance name and counter value.
for (DWORD i = 0; i < dwItemCount; i++)
{
wprintf(L"counter: %s, value %.20g\n", pItems[i].szName, pItems[i].FmtValue.doubleValue);
}
}
else
{
wprintf(L"Second PdhGetFormattedCounterArray call failed with 0x%x.\n", status);
goto cleanup;
}
free(pItems);
pItems = NULL;
dwBufferSize = dwItemCount = 0;
}
else
{
wprintf(L"malloc for PdhGetFormattedCounterArray failed.\n");
goto cleanup;
}
}
else
{
wprintf(L"PdhGetFormattedCounterArray failed with 0x%x.\n", status);
goto cleanup;
}
}
cleanup:
if (pItems)
free(pItems);
if (hQuery)
PdhCloseQuery(hQuery); // Closes all counter handles and the query handle
}
Заметка
Заголовок pdh.h определяет PdhGetFormattedCounterArray как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОДа. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.
Требования
| Требование | Ценность |
|---|---|
| минимальные поддерживаемые клиентские | Windows XP [только классические приложения] |
| минимальный поддерживаемый сервер | Windows Server 2003 [только классические приложения] |
| целевая платформа | Виндоус |
| заголовка | pdh.h |
| библиотеки |
Pdh.lib |
| DLL | Pdh.dll |