PdhGetFormattedCounterArrayA, fonction (pdh.h)
Retourne un tableau de valeurs de compteur mises en forme. Utilisez cette fonction lorsque vous souhaitez mettre en forme les valeurs de compteur d’un compteur qui contient un caractère générique pour le nom instance.
Syntaxe
PDH_FUNCTION PdhGetFormattedCounterArrayA(
[in] PDH_HCOUNTER hCounter,
[in] DWORD dwFormat,
[in, out] LPDWORD lpdwBufferSize,
[out] LPDWORD lpdwItemCount,
[out] PPDH_FMT_COUNTERVALUE_ITEM_A ItemBuffer
);
Paramètres
[in] hCounter
Gérez le compteur dont vous souhaitez mettre en forme la valeur actuelle. La fonction PdhAddCounter retourne ce handle.
[in] dwFormat
Détermine le type de données de la valeur mise en forme. Spécifiez l’une des valeurs suivantes.
Vous pouvez utiliser l’opérateur OR inclusif au niveau du bit (|) pour combiner le type de données avec l’un des facteurs de mise à l’échelle suivants.
[in, out] lpdwBufferSize
Taille de la mémoire tampon ItemBuffer , en octets. Si la valeur est zéro à l’entrée, la fonction retourne PDH_MORE_DATA et définit ce paramètre sur la taille de mémoire tampon requise. Si la mémoire tampon est supérieure à la taille requise, la fonction définit ce paramètre sur la taille réelle de la mémoire tampon utilisée. Si la taille spécifiée sur l’entrée est supérieure à zéro, mais inférieure à la taille requise, vous ne devez pas vous appuyer sur la taille retournée pour réallouer la mémoire tampon.
[out] lpdwItemCount
Nombre de valeurs de compteur dans la mémoire tampon ItemBuffer .
[out] ItemBuffer
Mémoire tampon allouée à l’appelant qui reçoit un tableau de structures PDH_FMT_COUNTERVALUE_ITEM ; les structures contiennent les valeurs de compteur. Définissez sur NULL si lpdwBufferSize a la valeur zéro.
Valeur retournée
Si la fonction réussit, elle retourne ERROR_SUCCESS.
Si la fonction échoue, la valeur de retour est un code d’erreur système ou un code d’erreur PDH. Voici les valeurs possibles.
| Code de retour | Description |
|---|---|
|
La mémoire tampon ItemBuffer n’est pas suffisamment grande pour contenir le nom de l’objet. Cette valeur de retour est attendue si lpdwBufferSize est égal à zéro en entrée. Si la taille spécifiée sur l’entrée est supérieure à zéro, mais inférieure à la taille requise, vous ne devez pas vous appuyer sur la taille retournée pour réallouer la mémoire tampon. |
|
Un paramètre n’est pas valide ou est mal mis en forme. Par exemple, sur certaines versions, vous pouvez recevoir cette erreur si la taille spécifiée sur l’entrée est supérieure à zéro, mais inférieure à la taille requise. |
|
Le handle de compteur n’est pas valide. |
Remarques
Vous devez appeler cette fonction deux fois, la première fois pour obtenir la taille de mémoire tampon requise (définissez ItemBuffer sur NULL et lpdwBufferSize sur 0) et la deuxième fois pour obtenir les données.
Les données du compteur sont verrouillées pendant la durée de l’appel à PdhGetFormattedCounterArray afin d’empêcher toute modification pendant le traitement de l’appel.
Exemples
L’exemple suivant montre comment utiliser cette fonction.
#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
}
Notes
L’en-tête pdh.h définit PdhGetFormattedCounterArray en tant qu’alias qui sélectionne automatiquement la version ANSI ou Unicode de cette fonction en fonction de la définition de la constante de préprocesseur UNICODE. La combinaison de l’utilisation de l’alias neutre en encodage avec du code qui n’est pas neutre en encodage peut entraîner des incompatibilités qui entraînent des erreurs de compilation ou d’exécution. Pour plus d’informations, consultez Conventions pour les prototypes de fonction.
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 |