PdhGetFormattedCounterArrayA 関数 (pdh.h)

[アーティクル]
11/20/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 バッファーのサイズ (バイト単位)。入力時に 0 の場合、関数はPDH_MORE_DATAを返し、このパラメーターを必要なバッファーサイズに設定します。バッファーが必要なサイズより大きい場合、関数はこのパラメーターを使用したバッファーの実際のサイズに設定します。入力で指定したサイズが 0 より大きく、必要なサイズより小さい場合は、返されたサイズに依存してバッファーを再割り当てしないでください。

[out] lpdwItemCount

ItemBuffer バッファー内のカウンター値の数。

[out] ItemBuffer

PDH_FMT_COUNTERVALUE_ITEM 構造体の配列を受け取る呼び出し元によって割り当てられたバッファー。構造体にはカウンター値が含まれています。 lpdwBufferSize が 0 の場合 NULL をに設定します。

戻り値

関数が成功すると、ERROR_SUCCESSが返されます。

関数が失敗した場合、戻り値はシステムエラーコードまたは PDH エラーコードです。使用できる値を次に示します。

リターンコード	形容
PDH_MORE_DATA	ItemBuffer バッファーは、オブジェクト名を格納するのに十分な大きさではありません。この戻り値は、lpdwBufferSize が入力時に 0 の場合に予期されます。入力で指定したサイズが 0 より大きく、必要なサイズより小さい場合は、返されたサイズに依存してバッファーを再割り当てしないでください。
PDH_INVALID_ARGUMENT	パラメーターが無効であるか、正しく書式設定されていません。たとえば、一部のリリースでは、入力で指定されたサイズが 0 より大きく、必要なサイズより小さい場合、このエラーが発生する可能性があります。
PDH_INVALID_HANDLE	カウンターハンドルが無効です。

備考

この関数を 2 回呼び出す必要があります。必要なバッファーサイズを取得する場合は、最初に必要なバッファーサイズ (ItemBuffer を NULL に設定し、lpdwBufferSize を 0 に )、2 回目にデータを取得します。

カウンターのデータは、呼び出しの処理中に変更されないように、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 プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして PdhGetFormattedCounterArray を定義します。エンコードに依存しないエイリアスをエンコードに依存しないコードと組み合わせて使用すると、コンパイルエラーやランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

必要条件

要件	価値
サポートされる最小クライアント	Windows XP [デスクトップアプリのみ]
サポートされる最小サーバー	Windows Server 2003 [デスクトップアプリのみ]
ターゲットプラットフォームの	ウィンドウズ
ヘッダー	pdh.h
ライブラリ	Pdh.lib
DLL	Pdh.dll

次の方法で共有

PdhGetFormattedCounterArrayA 関数 (pdh.h)

構文

パラメーター

戻り値

備考

例

必要条件

関連項目

フィードバック

その他のリソース