pdhGetFormattedCounterArrayA 函式 (pdh.h)

發行項
03/01/2024

傳回格式化計數器值的數位。當您想要格式化包含實例名稱通配符之計數器的計數器值時，請使用此函式。

語法

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

決定格式化值的數據類型。指定下列其中一個值。

值	意義
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 錯誤碼。以下是可能的值。

傳回碼	Description
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 標頭會根據 UNICODE 預處理器常數的定義，將 PdhGetFormattedCounterArray 定義為自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

規格需求

需求	值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2003 [僅限桌面應用程式]
目標平台	Windows
標頭	pdh.h
程式庫	Pdh.lib
Dll	Pdh.dll