PdhExpandCounterPathW-Funktion (pdh.h)
Untersucht den angegebenen Computer (oder den lokalen Computer, falls keiner angegeben ist) auf Leistungsindikatoren und Instanzen von Leistungsindikatoren, die den Feldhalterzeichenfolgen im Zählerpfad entsprechen.
Syntax
PDH_FUNCTION PdhExpandCounterPathW(
[in] LPCWSTR szWildCardPath,
[out] PZZWSTR mszExpandedPathList,
[in, out] LPDWORD pcchPathListLength
);
Parameter
[in] szWildCardPath
Null-beendete Zeichenfolge, die den zu erweiternden Zählerpfad enthält. 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 Indikatorenpfade empfängt, die der Feldhalterspezifikation in szWildCardPath entsprechen. Jeder Zählerpfad in dieser Liste wird mit einem NULL-Zeichen beendet. Die Liste wird mit zwei NULL-Zeichen beendet. Legen Sie auf NULL fest, wenn pcchPathListLength 0 ist.
[in, out] pcchPathListLength
Größe des mszExpandedPathList-Puffers in TCHARs. Wenn bei der Eingabe null angegeben wird, 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 0, aber kleiner als die erforderliche Größe ist, sollten Sie sich nicht auf die zurückgegebene Größe verlassen, um den Puffer neu zuzurücken.
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt sie ERROR_SUCCESS zurück.
Wenn die Funktion fehlschlägt, ist der Rückgabewert ein Systemfehlercode oder ein PDH-Fehlercode.
| Rückgabecode | Beschreibung |
|---|---|
|
Der Puffer mszExpandedPathList ist zu klein, um die Liste der Pfade zu enthalten. Dieser Rückgabewert wird erwartet, wenn pcchPathListLength bei der Eingabe 0 ist. Wenn die angegebene Größe für die Eingabe größer als 0, aber kleiner als die erforderliche Größe ist, sollten Sie sich nicht auf die zurückgegebene Größe verlassen, um den Puffer neu zuzurücken. |
|
Ein Parameter ist nicht gültig. Bei einigen Releases kann dieser Fehler beispielsweise angezeigt werden, 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. |
Hinweise
Sie sollten diese Funktion zweimal aufrufen, zum ersten Mal zum Abrufen der erforderlichen Puffergröße (Festlegen von mszExpandedPathList auf NULL und pcchPathListLength auf 0) und beim zweiten Mal zum Abrufen der Daten.
Das allgemeine Format des Indikatorpfads lautet wie folgt:
\computer\object(parent/instance#index)\counter
Die Komponenten übergeordneter, instance, Index und Zähler des Zählerpfads können entweder einen gültigen Namen oder ein Feldhalterzeichen enthalten. Die Computer-, übergeordneten, instance- und Indexkomponenten sind nicht für alle Indikatoren erforderlich.
Die Indikatorenpfade, die Sie verwenden müssen, werden vom Zähler selbst bestimmt. Das LogicalDisk-Objekt verfügt beispielsweise über einen instance Index, sodass Sie den #index oder einen Feldhalter angeben müssen. Daher können Sie das folgende Format verwenden:
\LogicalDisk(/#*)*
Im Vergleich dazu erfordert das Process-Objekt keinen instance Index. Daher können Sie das folgende Format verwenden:
\Process(*)\ID Process
Im Folgenden ist eine Liste der möglichen Formate aufgeführt:
- \\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 im instance Namen ein Feldhalterzeichen angegeben ist, werden alle Instanzen des angegebenen Objekts und des übergeordneten Objekts zurückgegeben, wenn alle instance Namen, die dem angegebenen Index entsprechen, mit dem Feldhalterzeichen übereinstimmen.
Wenn im Leistungsindikatornamen ein Feldhalterzeichen angegeben ist, werden alle Leistungsindikatoren des angegebenen Objekts zurückgegeben.
Partielle Übereinstimmungen mit Zählerpfadzeichenfolgen (z. B. "pro*") werden nicht unterstützt.
Beispiele
Im folgenden Beispiel wird veranschaulicht, wie diese Funktion ausgeführt wird.
#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);
}
}
Hinweis
Der pdh.h-Header definiert PdhExpandCounterPath als Alias, der automatisch die ANSI- oder Unicode-Version dieser Funktion basierend auf der Definition der UNICODE-Präprozessorkonstante auswählt. Das Mischen der Verwendung des codierungsneutralen Alias mit nicht codierungsneutralem Code kann zu Nichtübereinstimmungen führen, die zu Kompilierungs- oder Laufzeitfehlern führen. Weitere Informationen finden Sie unter Konventionen für Funktionsprototypen.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [nur Desktop-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [nur Desktop-Apps] |
| Zielplattform | Windows |
| Kopfzeile | pdh.h |
| Bibliothek | Pdh.lib |
| DLL | Pdh.dll |