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

傳回碼	Description
PDH_INVALID_HANDLE	查詢句柄無效。
PDH_NO_DATA	查詢目前沒有任何計數器。

備註

當您呼叫 PdhCloseQuery 函式時，PDH 會終止線程。 如果您多次呼叫 PdhCollectQueryDataEx ，則每個後續呼叫都會終止先前呼叫中的線程，然後啟動新的線程。

當只針對一個計數器實例的數據呼叫 PdhCollectQueryDataEx ，且計數器實例不存在時，函式會傳回PDH_NO_DATA。 不過，如果查詢來自多個計數器的數據，即使其中一個計數器實例不存在， 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
程式庫	Pdh.lib
Dll	Pdh.dll

另請參閱

CreateEvent

PdhCollectQueryData

PdhOpenQuery