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 de l’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
[out] lpdwItemCount
Nombre de valeurs de compteur dans la mémoire tampon ItemBuffer.
[out] ItemBuffer
Mémoire tampon allouée par l’appelant qui reçoit un tableau de structures PDH_FMT_COUNTERVALUE_ITEM ; les structures contiennent les valeurs de compteur. Défini sur NULL si lpdwBufferSize est égal à zéro.
Valeur de retour
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.
| Retourner le code | Description |
|---|---|
|
La mémoire tampon ItemBuffer |
|
Un paramètre n’est pas valide ou n’est pas correctement 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 pour 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
}
Note
L’en-tête pdh.h définit PdhGetFormattedCounterArray comme 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. Le mélange 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Windows XP [applications de bureau uniquement] |
| serveur minimum pris en charge | Windows Server 2003 [applications de bureau uniquement] |
| plateforme cible | Windows |
| d’en-tête | pdh.h |
| bibliothèque | Pdh.lib |
| DLL | Pdh.dll |