Функция PdhGetFormattedCounterArrayA (pdh.h)
Возвращает массив форматированных значений счетчиков. Используйте эту функцию, если требуется отформатировать значения счетчика, содержащего подстановочный знак для имени экземпляра.
Синтаксис
PDH_FUNCTION PdhGetFormattedCounterArrayA(
[in] PDH_HCOUNTER hCounter,
[in] DWORD dwFormat,
[in, out] LPDWORD lpdwBufferSize,
[out] LPDWORD lpdwItemCount,
[out] PPDH_FMT_COUNTERVALUE_ITEM_A ItemBuffer
);
Параметры
[in] hCounter
Дескриптор для счетчика, текущее значение которого требуется отформатировать. Функция PdhAddCounter возвращает этот дескриптор.
[in] dwFormat
Определяет тип данных форматированного значения. Укажите одно из следующих значений.
Для объединения типа данных с одним из следующих факторов масштабирования можно использовать побитовый оператор ИЛИ (|).
[in, out] lpdwBufferSize
Размер буфера ItemBuffer в байтах. Если входные данные равны нулю, функция возвращает PDH_MORE_DATA и задает для этого параметра требуемый размер буфера. Если размер буфера превышает требуемый размер, функция задает для этого параметра фактический размер использованного буфера. Если указанный размер входных данных больше нуля, но меньше требуемого размера, не следует полагаться на возвращаемый размер для перераспределения буфера.
[out] lpdwItemCount
Число значений счетчиков в буфере ItemBuffer .
[out] ItemBuffer
Буфер, выделенный вызывающим объектом, который получает массив PDH_FMT_COUNTERVALUE_ITEM структур; структуры содержат значения счетчиков. Если значение lpdwBufferSize равно нулю, задайте значение NULL.
Возвращаемое значение
Если функция завершается успешно, она возвращает ERROR_SUCCESS.
Если функция завершается сбоем, возвращаемое значение представляет собой код системной ошибки или код ошибки PDH. Ниже приведены возможные значения.
| Код возврата | Описание |
|---|---|
|
Буфер ItemBuffer недостаточно велик, чтобы содержать имя объекта. Это возвращаемое значение ожидается, если lpdwBufferSize равно нулю на входных данных. Если указанный размер входных данных больше нуля, но меньше требуемого размера, не следует полагаться на возвращаемый размер для перераспределения буфера. |
|
Параметр недопустим или неправильно отформатирован. Например, в некоторых выпусках эта ошибка может возникнуть, если указанный размер входных данных больше нуля, но меньше требуемого размера. |
|
Недопустимый дескриптор счетчика. |
Комментарии
Эту функцию следует вызывать дважды: первый раз, чтобы получить требуемый размер буфера (задайте для ItemBuffer значение NULL , а для lpdwBufferSize — значение 0), а второй раз — для получения данных.
Данные счетчика блокируются на время вызова PdhGetFormattedCounterArray , чтобы предотвратить любые изменения во время обработки вызова.
Примеры
В следующем примере показано, как использовать эту функцию.
#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 [только классические приложения] |
| Целевая платформа | Windows |
| Header | pdh.h |
| Библиотека | Pdh.lib |
| DLL | Pdh.dll |