PdhGetFormattedCounterArrayW-Funktion (pdh.h)
Gibt ein Array mit formatierten Zählerwerten zurück. Verwenden Sie diese Funktion, wenn Sie die Zählerwerte eines Zählers formatieren möchten, der ein Wildcardzeichen für den Namen der Instanz enthält.
Syntax
PDH_FUNCTION PdhGetFormattedCounterArrayW(
[in] PDH_HCOUNTER hCounter,
[in] DWORD dwFormat,
[in, out] LPDWORD lpdwBufferSize,
[out] LPDWORD lpdwItemCount,
[out] PPDH_FMT_COUNTERVALUE_ITEM_W ItemBuffer
);
Parameter
[in] hCounter
Behandeln Sie den Zähler, dessen aktueller Wert Sie formatieren möchten. Die PdhAddCounter--Funktion gibt diesen Handle zurück.
[in] dwFormat
Bestimmt den Datentyp des formatierten Werts. Geben Sie einen der folgenden Werte an.
Sie können den bitweise inklusiven OR-Operator (|) verwenden, um den Datentyp mit einem der folgenden Skalierungsfaktoren zu kombinieren.
[in, out] lpdwBufferSize
Größe des ItemBuffer- Puffers in Byte. Wenn null bei eingaben, gibt die Funktion PDH_MORE_DATA zurück und legt diesen Parameter auf die erforderliche Puffergröße fest. Wenn der Puffer größer als die erforderliche Größe ist, legt die Funktion diesen Parameter auf die tatsächliche Größe des verwendeten Puffers fest. Wenn die angegebene Größe für die Eingabe größer als null, aber kleiner als die erforderliche Größe ist, sollten Sie nicht auf die zurückgegebene Größe zurückgreifen, um den Puffer neu zuzuweisen.
[out] lpdwItemCount
Anzahl der Zählerwerte im ItemBuffer Puffer.
[out] ItemBuffer
Vom Aufrufer zugewiesener Puffer, der ein Array von PDH_FMT_COUNTERVALUE_ITEM Strukturen empfängt; die Strukturen enthalten die Zählerwerte. Wird auf NULL- festgelegt, wenn lpdwBufferSize null ist.
Rückgabewert
Wenn die Funktion erfolgreich ist, wird ERROR_SUCCESS zurückgegeben.
Wenn die Funktion fehlschlägt, ist der Rückgabewert ein Systemfehlercode oder ein PDH-Fehlercode. Im Folgenden sind mögliche Werte aufgeführt.
| Rückgabecode | Beschreibung |
|---|---|
|
Der ItemBuffer- Puffer ist nicht groß genug, um den Objektnamen zu enthalten. Dieser Rückgabewert wird erwartet, wenn lpdwBufferSize für eingabe null ist. Wenn die angegebene Größe für die Eingabe größer als null, aber kleiner als die erforderliche Größe ist, sollten Sie nicht auf die zurückgegebene Größe zurückgreifen, um den Puffer neu zuzuweisen. |
|
Ein Parameter ist ungültig oder falsch formatiert. Bei einigen Versionen können Sie diesen Fehler z. B. erhalten, wenn die angegebene Größe für die Eingabe größer als 0, aber kleiner als die erforderliche Größe ist. |
|
Der Zählerziehpunkt ist ungültig. |
Bemerkungen
Sie sollten diese Funktion zweimal aufrufen, zum ersten Mal, um die erforderliche Puffergröße abzurufen (ItemBuffer- auf NULL- und lpdwBufferSize auf 0 festgelegt) und das zweite Mal, um die Daten abzurufen.
Die Daten für den Zähler werden für die Dauer des Aufrufs an PdhGetFormattedCounterArray gesperrt, um Änderungen während der Verarbeitung des Anrufs zu verhindern.
Beispiele
Das folgende Beispiel zeigt, wie diese Funktion verwendet wird.
#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
}
Anmerkung
Der pdh.h-Header definiert PdhGetFormattedCounterArray als Alias, der die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante automatisch auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit Code, der nicht codierungsneutral ist, kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Anforderung | Wert |
|---|---|
| mindestens unterstützte Client- | Windows XP [nur Desktop-Apps] |
| mindestens unterstützte Server- | Windows Server 2003 [Nur Desktop-Apps] |
| Zielplattform- | Fenster |
| Header- | pdh.h |
| Library | Pdh.lib |
| DLL- | Pdh.dll |