PdhGetFormattedCounterArrayW 函数（pdh.h）

项目
11/20/2024

返回格式化计数器值的数组。如果要设置包含实例名称通配符的计数器值的计数器值的格式，请使用此函数。

语法

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

确定格式化值的数据类型。指定以下值之一。

价值	意义
PDH_FMT_DOUBLE	以双精度浮点实数的形式返回数据。
PDH_FMT_LARGE	以 64 位整数的形式返回数据。
PDH_FMT_LONG	以长整数的形式返回数据。

可以使用按位非独占 OR 运算符（|）将数据类型与以下缩放因子之一组合在一起。

价值	意义
PDH_FMT_NOSCALE	不要应用计数器的默认缩放因子。
PDH_FMT_NOCAP100	大于 100 的计数器值（例如，测量多处理器计算机上的处理器负载的计数器值）不会重置为 100。默认行为是计数器值上限为 100。
PDH_FMT_1000	将实际值乘以 1,000。

[in, out] lpdwBufferSize

ItemBuffer 缓冲区的大小（以字节为单位）。如果输入为零，则函数将返回PDH_MORE_DATA并将此参数设置为所需的缓冲区大小。如果缓冲区大于所需大小，则函数会将此参数设置为所使用的缓冲区的实际大小。如果输入上的指定大小大于零，但小于所需大小，则不应依赖返回的大小来重新分配缓冲区。

[out] lpdwItemCount

ItemBuffer 缓冲区中的计数器值数。

[out] ItemBuffer

接收 PDH_FMT_COUNTERVALUE_ITEM 结构的数组的调用方分配的缓冲区;结构包含计数器值。如果 lpdwBufferSize 为零，则设置为 NULL。

返回值

如果函数成功，它将返回ERROR_SUCCESS。

如果函数失败，则返回值为系统错误代码或 PDH 错误代码。以下是可能的值。

返回代码	描述
PDH_MORE_DATA	itemBuffer 缓冲区不够大，无法包含对象名称。如果输入时 lpdwBufferSize 为零，则预期返回值。如果输入上的指定大小大于零，但小于所需大小，则不应依赖返回的大小来重新分配缓冲区。
PDH_INVALID_ARGUMENT	参数无效或格式不正确。例如，在某些版本中，如果输入上的指定大小大于零但小于所需大小，则可能会收到此错误。
PDH_INVALID_HANDLE	计数器句柄无效。

言论

应调用此函数两次，第一次获取所需的缓冲区大小（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 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。有关详细信息，请参阅函数原型的约定。

要求

要求	价值
最低支持的客户端	Windows XP [仅限桌面应用]
支持的最低服务器	Windows Server 2003 [仅限桌面应用]
目标平台	窗户
标头	pdh.h
库	Pdh.lib
DLL	Pdh.dll