PdhExpandWildCardPathA-Funktion (pdh.h)
Untersucht den angegebenen Computer oder die angegebene Protokolldatei und gibt die Zählerpfade zurück, die dem angegebenen Indikatorpfad entsprechen, der Wildcardzeichen enthält.
Um Handles für Datenquellen zu verwenden, verwenden Sie die PdhExpandWildCardPathH-Funktion .
Syntax
PDH_FUNCTION PdhExpandWildCardPathA(
[in] LPCSTR szDataSource,
[in] LPCSTR szWildCardPath,
[out] PZZSTR mszExpandedPathList,
[in, out] LPDWORD pcchPathListLength,
[in] DWORD dwFlags
);
Parameter
[in] szDataSource
Null-terminierte Zeichenfolge, die den Namen einer Protokolldatei enthält. Die Funktion verwendet die in der Protokolldatei definierten Leistungsobjekte und Leistungsindikatoren, um den im szWildCardPath-Parameter angegebenen Pfad zu erweitern.
Bei NULL durchsucht die Funktion den in szWildCardPath angegebenen Computer.
[in] szWildCardPath
Null-beendete Zeichenfolge, die den zu erweiternden Zählerpfad angibt. Die maximale Länge eines Indikatorpfads ist PDH_MAX_COUNTER_PATH.
Wenn der szDataSource-ParameterNULL ist, durchsucht die Funktion den im Pfad angegebenen Computer nach Übereinstimmungen. Wenn der Pfad keinen Computer angibt, durchsucht die Funktion den lokalen Computer.
[out] mszExpandedPathList
Vom Aufrufer zugewiesener Puffer, der eine Liste mit null-endendierten Zählerpfaden empfängt, die der Wildcard-Spezifikation in szWildCardPath entsprechen. Die Liste wird durch zwei NULL-Zeichen beendet. Legen Sie auf NULL fest, wenn pcchPathListLength null ist.
[in, out] pcchPathListLength
Größe des mszExpandedPathList-Puffers in TCHARs. Wenn null bei der Eingabe und das Objekt vorhanden ist, 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 bei der Eingabe größer als null, aber kleiner als die erforderliche Größe ist, sollten Sie sich nicht auf die zurückgegebene Größe verlassen, um den Puffer neu zuzuweisen.
[in] dwFlags
Flags, die angeben, welche Wildcardzeichen nicht erweitert werden sollen. Sie können ein oder mehrere Flags angeben.
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 puffer mszExpandedPathList ist nicht groß genug, um die Liste der Pfade zu enthalten. Dieser Rückgabewert wird erwartet, wenn pcchPathListLength bei der Eingabe null ist. Wenn die angegebene Größe bei der Eingabe größer als null, aber kleiner als die erforderliche Größe ist, sollten Sie sich nicht auf die zurückgegebene Größe verlassen, um den Puffer neu zuzuweisen. |
|
Ein Parameter ist nicht gültig. Bei einigen Releases kann dieser Fehler beispielsweise angezeigt werden, wenn die angegebene Größe bei der Eingabe größer als null, aber kleiner als die erforderliche Größe ist. |
|
Das angegebene Objekt enthält keine instance. |
|
Speicher kann nicht zugewiesen werden, um diese Funktion zu unterstützen. |
|
Das angegebene Objekt kann auf dem Computer oder in der Protokolldatei nicht gefunden werden. |
Hinweise
Sie sollten diese Funktion zweimal aufrufen, beim ersten Abrufen der erforderlichen Puffergröße (legen Sie mszExpandedPathList auf NULL und pcchPathListLength auf 0 fest), und beim zweiten Mal, um die Daten abzurufen.
PdhExpandWildCardPath unterscheidet sich auf folgende Weise von PdhExpandCounterPath :
- Hiermit können Sie steuern, welche Wildcardzeichen erweitert werden.
- Der Inhalt einer Protokolldatei kann als Quelle von Indikatornamen verwendet werden.
\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 Wildcardzeichen enthalten. Die Komponenten computer, übergeordnete, instance und Index sind nicht für alle Leistungsindikatoren erforderlich.
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 übergeordneten Namen ein Wildcardzeichen angegeben wird, werden alle Instanzen des angegebenen Objekts zurückgegeben, die den angegebenen instance- und Indikatorfeldern entsprechen. Beispiel: \object(*/instance)\counter.
Wenn im namen des instance ein Wildcardzeichen 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 Wildcardzeichen übereinstimmen. Beispiel: \object(parent/*)\counter. Wenn das Objekt keine instance enthält, tritt ein Fehler auf.
Wenn im Zählernamen ein Wildcardzeichen angegeben ist, werden alle Leistungsindikatoren des angegebenen Objekts zurückgegeben.
Partielle Übereinstimmungen von Zählerpfadzeichenfolgen (z. B. "pro*") werden unterstützt.
Vor Windows Vista: Partielle Wildcard-Übereinstimmungen werden nicht unterstützt.
Hinweis
Der pdh.h-Header definiert PdhExpandWildCardPath 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
| 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 |