Fonction PdhCollectQueryDataEx (pdh.h)

Article
03/01/2024

Utilise un thread distinct pour collecter la valeur de données brutes actuelle pour tous les compteurs de la requête spécifiée. La fonction signale ensuite l’événement défini par l’application et attend l’intervalle de temps spécifié avant de retourner.

Syntaxe

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

Paramètres

[in] hQuery

Gérer la requête. La requête identifie les compteurs que vous souhaitez collecter. La fonction PdhOpenQuery retourne ce handle.

[in] dwIntervalTime

Intervalle de temps d’attente, en secondes.

[in] hNewDataEvent

Gérez l’événement que vous souhaitez signaler par PDH après l’expiration de l’intervalle de temps. Pour créer un objet d’événement, appelez la fonction CreateEvent .

Valeur retournée

Si la fonction réussit, elle retourne ERROR_SUCCESS.

Si la fonction échoue, la valeur renvoyée est un code d’erreur système ou un code d’erreur PDH. Voici les valeurs possibles.

Code de retour	Description
PDH_INVALID_HANDLE	Le handle de requête n’est pas valide.
PDH_NO_DATA	La requête n’a actuellement aucun compteur.

Remarques

PDH arrête le thread lorsque vous appelez la fonction PdhCloseQuery . Si vous appelez PdhCollectQueryDataEx plusieurs fois, chaque appel suivant met fin au thread de l’appel précédent, puis démarre un nouveau thread.

Lorsque PdhCollectQueryDataEx est appelé pour les données d’un seul compteur instance et que le compteur instance n’existe pas, la fonction retourne PDH_NO_DATA. Toutefois, si les données de plusieurs compteurs sont interrogées, PdhCollectQueryDataEx peut retourner ERROR_SUCCESS même si l’une des instances de compteur n’existe pas encore. Cela est dû au fait qu’il n’est pas connu si le compteur spécifié instance n’existe pas ou s’il existera mais n’a pas encore été créé. Dans ce cas, appelez PdhGetRawCounterValue ou PdhGetFormattedCounterValue pour chacune des instances de compteur intéressantes pour déterminer si elles existent.

PDH stocke les valeurs de compteur brutes pour la collection actuelle et précédente. Si vous souhaitez récupérer la valeur actuelle du compteur brut, appelez la fonction PdhGetRawCounterValue . Si vous souhaitez calculer une valeur d’affichage pour la valeur du compteur, appelez pdhGetFormattedCounterValue. Si le chemin du compteur contient un caractère générique pour le nom instance, appelez les fonctions PdhGetRawCounterArray et PdhGetFormattedCounterArray, respectivement.

Exemples

L’exemple suivant montre comment utiliser cette fonction.


#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);
    }
}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	pdh.h
Bibliothèque	Pdh.lib
DLL	Pdh.dll

Voir aussi

CreateEvent

PdhCollectQueryData

PdhOpenQuery

Partager via