PdhCollectQueryDataEx 関数 (pdh.h)

  • [アーティクル]

別のスレッドを使用して、指定したクエリ内のすべてのカウンターの現在の生データ値を収集します。 その後、関数はアプリケーション定義のイベントを通知し、指定された時間間隔を待機してからを返します。

構文

PDH_FUNCTION PdhCollectQueryDataEx(
  [in] PDH_HQUERY hQuery,
  [in] DWORD      dwIntervalTime,
  [in] HANDLE     hNewDataEvent
);

パラメーター

[in] hQuery

クエリのハンドル。 クエリは、収集するカウンターを識別します。 PdhOpenQuery 関数は、このハンドルを返します。

[in] dwIntervalTime

待機する時間間隔 (秒単位)。

[in] hNewDataEvent

時間間隔の有効期限が切れた後に PDH が通知するイベントを処理します。 イベント オブジェクトを作成するには、 CreateEvent 関数を呼び出します。

戻り値

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

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

リターン コード 説明
PDH_INVALID_HANDLE
 クエリ ハンドルが無効です。
PDH_NO_DATA
 現在、クエリにはカウンターがありません。

注釈

PdhCloseQuery 関数を呼び出すと、PDH はスレッドを終了します。 PdhCollectQueryDataEx を複数回呼び出すと、後続の呼び出しごとに前の呼び出しからスレッドが終了し、新しいスレッドが開始されます。

PdhCollectQueryDataEx が 1 つのカウンター インスタンスからのデータに対してのみ呼び出され、カウンター インスタンスが存在しない場合、関数はPDH_NO_DATAを返します。 ただし、複数のカウンターのデータに対してクエリを実行すると、カウンター インスタンスの 1 つがまだ存在しない場合でも、 PdhCollectQueryDataEx はERROR_SUCCESSを返す可能性があります。 これは、指定したカウンター インスタンスが存在しないか、存在するが作成されていないのかは不明であるためです。 この場合は、対象のカウンター インスタンスごとに PdhGetRawCounterValue または PdhGetFormattedCounterValue を呼び出して、存在するかどうかを判断します。

PDH は、現在のコレクションと以前のコレクションの生カウンター値を格納します。 現在の生カウンター値を取得する場合は、 PdhGetRawCounterValue 関数を呼び出します。 カウンター値の表示可能な値を計算する場合は、 PdhGetFormattedCounterValue を呼び出します。 カウンター パスにインスタンス名のワイルドカードが含まれている場合は、代わりに PdhGetRawCounterArray 関数と PdhGetFormattedCounterArray 関数をそれぞれ呼び出します。

例

次の例は、この関数の使用方法を示しています。


#include <windows.h>
#include <stdio.h>
#include <stdlib.h>
#include <pdh.h>

#pragma comment(lib, "pdh.lib")

CONST PWSTR COUNTER_NAME    = L"\\Processor(0)\\% Processor Time";
CONST ULONG SAMPLE_COUNT    = 10;
CONST ULONG SAMPLE_INTERVAL = 2;

void wmain(void)
{
    PDH_STATUS Status;
    HANDLE Event = NULL;
    PDH_HQUERY Query = NULL;
    PDH_HCOUNTER Counter;
    ULONG WaitResult;
    ULONG CounterType;
    PDH_FMT_COUNTERVALUE DisplayValue;

    Status = PdhOpenQuery(NULL, 0, &Query);
    if (Status != ERROR_SUCCESS) 
    {
        wprintf(L"\nPdhOpenQuery failed with status 0x%x.", Status);
        goto Cleanup;
    }

    Status = PdhAddCounter(Query, COUNTER_NAME, 0, &Counter);
    if (Status != ERROR_SUCCESS) 
    {
        wprintf(L"\nPdhAddCounter failed with 0x%x.", Status);
        goto Cleanup;
    }

    //
    // Calculating the formatted value of some counters requires access to the
    // value of a previous sample. Make this call to get the first sample value
    // populated, to be used later for calculating the next sample.
    //

    Status = PdhCollectQueryData(Query);
    if (Status != ERROR_SUCCESS) 
    {
        wprintf(L"\nPdhCollectQueryData failed with status 0x%x.", Status);
        goto Cleanup;
    }

    //
    // This will create a separate thread that will collect raw counter data
    // every 2 seconds and set the supplied Event.
    //

    Event = CreateEvent(NULL, FALSE, FALSE, L"MyEvent");
    if (Event == NULL) 
    {
        wprintf(L"\nCreateEvent failed with status 0x%x.", GetLastError());
        goto Cleanup;
    }

    Status = PdhCollectQueryDataEx(Query, SAMPLE_INTERVAL, Event);
    if (Status != ERROR_SUCCESS) 
    {
        wprintf(L"\nPdhCollectQueryDataEx failed with status 0x%x.", Status);
        goto Cleanup;
    }

    //
    // Collect and format 10 samples, 2 seconds apart.
    //

    for (ULONG i = 0; i < SAMPLE_COUNT; i++) 
    {
        WaitResult = WaitForSingleObject(Event, INFINITE);

        if (WaitResult == WAIT_OBJECT_0) 
        {
            Status = PdhGetFormattedCounterValue(Counter, PDH_FMT_DOUBLE, &CounterType, &DisplayValue);

            if (Status == ERROR_SUCCESS) 
            {
                wprintf(L"\nCounter Value: %.20g", DisplayValue.doubleValue);
            } 
            else 
            {
                wprintf(L"\nPdhGetFormattedCounterValue failed with status 0x%x.", Status);
                goto Cleanup;
            }
        } 
        else if (WaitResult == WAIT_FAILED) 
        {
            wprintf(L"\nWaitForSingleObject failed with status 0x%x.", GetLastError());
            goto Cleanup;
        }
    }

Cleanup:

    if (Event) 
    {
        CloseHandle(Event);
    }

    //
    // This will close both the Query handle and all associated Counter handles
    // returned by PdhAddCounter.
    //

    if (Query) 
    {
        PdhCloseQuery(Query);
    }
}

要件

要件 値
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー pdh.h
Library Pdh.lib
[DLL] Pdh.dll

こちらもご覧ください

CreateEvent

PdhCollectQueryData

PdhOpenQuery