PdhExpandWildCardPathA-Funktion (pdh.h)

  • Artikel

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.

Hinweis Sie müssen eine der erforderlichen Größe unter Windows XP hinzufügen.
 

[in] dwFlags

Flags, die angeben, welche Wildcardzeichen nicht erweitert werden sollen. Sie können ein oder mehrere Flags angeben.

Wert Bedeutung
PDH_NOEXPANDCOUNTERS
 Erweitern Sie den Zählernamen nicht, wenn der Pfad ein Wildcardzeichen für den Zählernamen enthält.
PDH_NOEXPANDINSTANCES
 Erweitern Sie den instance Namen nicht, wenn der Pfad ein Feldhalterzeichen für übergeordnete instance, instance Namen oder instance Index enthält.
PDH_REFRESHCOUNTERS
 Aktualisieren Sie die Zählerliste.

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
PDH_MORE_DATA
 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.
PDH_INVALID_ARGUMENT
 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.
PDH_INVALID_PATH
 Das angegebene Objekt enthält keine instance.
PDH_MEMORY_ALLOCATION_FAILURE
 Speicher kann nicht zugewiesen werden, um diese Funktion zu unterstützen.
PDH_CSTATUS_NO_OBJECT
 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 :

  1. Hiermit können Sie steuern, welche Wildcardzeichen erweitert werden.
  2. Der Inhalt einer Protokolldatei kann als Quelle von Indikatornamen verwendet werden.
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 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
Verwenden Sie ein Sternchen (*) als Platzhalterzeichen, z. B. \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

Weitere Informationen

PdhEnumObjectItems

PdhEnumObjects

PdhExpandCounterPath

PdhExpandWildCardPathH