PdhExpandCounterPathA-Funktion (pdh.h)
Überprüft den angegebenen Computer (oder lokalen Computer, wenn keine angegeben ist) auf Leistungsindikatoren und Instanzen von Zählern, die den Wildcardzeichenfolgen im Zählerpfad entsprechen.
Syntax
PDH_FUNCTION PdhExpandCounterPathA(
[in] LPCSTR szWildCardPath,
[out] PZZSTR mszExpandedPathList,
[in, out] LPDWORD pcchPathListLength
);
Parameter
[in] szWildCardPath
null-terminated string that contains the counter path to expand. Die Funktion durchsucht den im Pfad angegebenen Computer nach Übereinstimmungen. Wenn der Pfad keinen Computer angibt, durchsucht die Funktion den lokalen Computer. Die maximale Länge eines Zählerpfads ist PDH_MAX_COUNTER_PATH.
[out] mszExpandedPathList
Vom Aufrufer zugewiesener Puffer, der die Liste der erweiterten Zählerpfade empfängt, die der Wildcardspezifikation in szWildCardPathentsprechen. Jeder Indikatorpfad in dieser Liste wird durch ein NULL- Zeichen beendet. Die Liste wird mit zwei NULL- Zeichen beendet. Wird auf NULL- festgelegt, wenn pcchPathListLength null ist.
[in, out] pcchPathListLength
Größe des mszExpandedPathList- Puffers in TCHARs-. 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.
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.
| Rückgabecode | Beschreibung |
|---|---|
|
Der mszExpandedPathList Puffer ist zu klein, um die Liste der Pfade zu enthalten. Dieser Rückgabewert wird erwartet, wenn pcchPathListLength bei eingaben 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. 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. |
|
Speicher kann nicht zugewiesen werden, um diese Funktion zu unterstützen. |
Bemerkungen
Sie sollten diese Funktion zweimal aufrufen, zum ersten Mal, um die erforderliche Puffergröße abzurufen (mszExpandedPathList auf NULL- und pcchPathListLength- auf 0 festgelegt) und das zweite Mal, um die Daten abzurufen.
Das allgemeine Zählerpfadformat lautet wie folgt:
\computer\object(parent/instance#index)\counter
Die übergeordneten Komponenten, Instanzen, Index und Zähler des Zählerpfads können entweder einen gültigen Namen oder ein Wildcardzeichen enthalten. Der Computer, das übergeordnete Element, die Instanz und die Indexkomponenten sind für alle Leistungsindikatoren nicht erforderlich.
Die Zählerpfade, die Sie verwenden müssen, werden vom Zähler selbst bestimmt. Das LogicalDisk-Objekt verfügt z. B. über einen Instanzindex, daher müssen Sie die #index oder einen Wildcard angeben. Daher können Sie das folgende Format verwenden:
\LogicalDisk(/#*)*
Im Vergleich dazu erfordert das Process-Objekt keinen Instanzindex. Daher können Sie das folgende Format verwenden:
\Process(*)\ID Process
Es folgt eine Liste der möglichen Formate:
- \\computer\object(parent/instance#index)\counter
- \\computer\object(parent/instance)\counter
- \\computer\object(instance#index)\counter
- \\computer\object(instance)\counter
- \\computer\object\counter
- \object(parent/instance#index)\counter
- \object(parent/instance)\counter
- \object(instance#index)\counter
- \object(instance)\counter
- \object\counter
Wenn ein Wildcardzeichen im Instanznamen angegeben wird, werden alle Instanzen des angegebenen Objekts und des übergeordneten Objekts zurückgegeben, wenn alle Instanznamen, die dem angegebenen Index entsprechen, mit dem Wildcardzeichen übereinstimmen.
Wenn ein Wildcardzeichen im Zählernamen angegeben ist, werden alle Zähler des angegebenen Objekts zurückgegeben.
Teilzählerpfadzeichenfolgen-Übereinstimmungen (z. B. "pro*") werden nicht unterstützt.
Beispiele
Das folgende Beispiel veranschaulicht, wie diese Funktion funktioniert.
#include <windows.h>
#include <stdio.h>
#include <stdlib.h>
#include <pdh.h>
#include <pdhmsg.h>
#pragma comment(lib, "pdh.lib")
CONST PWSTR WILDCARD_PATH = L"\\Processor(*)\\*";
void wmain(void)
{
PDH_STATUS Status;
PWSTR EndOfPaths;
PWSTR Paths = NULL;
DWORD BufferSize = 0;
Status = PdhExpandCounterPath(WILDCARD_PATH, Paths, &BufferSize);
while (Status == PDH_MORE_DATA)
{
Paths = (PWSTR)malloc(BufferSize * sizeof(WCHAR));
Status = PdhExpandCounterPath(WILDCARD_PATH, Paths, &BufferSize);
}
if (Status != ERROR_SUCCESS)
{
wprintf(L"\nPdhExpandCounterPath failed with status 0x%x", Status);
goto Cleanup;
}
if (Paths == NULL)
{
wprintf(L"\nThe counter path %s cannot be expanded.", WILDCARD_PATH);
goto Cleanup;
}
EndOfPaths = Paths + BufferSize;
// On Vista and later operating systems, the buffer is terminated with two
// null-terminator characters; however, on earlier systems, the buffer is
// not terminated with two null-terminator characters. This covers both cases.
for (PWSTR p = Paths; ((p != EndOfPaths) && (*p != L'\0')); p += wcslen(p) + 1)
{
wprintf(L"\n%s", p);
}
Cleanup:
if (Paths)
{
free(Paths);
}
}
Anmerkung
Der pdh.h-Header definiert PdhExpandCounterPath 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 |