Freigeben über

PdhExpandWildCardPathA-Funktion (pdh.h)

  • Artikel

Untersucht den angegebenen Computer oder die angegebene Protokolldatei und gibt diese Zählerpfade zurück, die dem angegebenen Zählerpfad 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--terminated-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.

Wenn NULL-, durchsucht die Funktion den in szWildCardPathangegebenen Computer.

[in] szWildCardPath

Null--terminated-Zeichenfolge, die den zu erweiternden Zählerpfad angibt. Die maximale Länge eines Zählerpfads ist PDH_MAX_COUNTER_PATH.

Wenn der parameter szDataSourceNULList, 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 der NULL--terminated-Counterpfade empfängt, die der Wildcardspezifikation im szWildCardPathentsprechen. Die Liste wird durch zwei NULL- Zeichen beendet. Wird auf NULL- festgelegt, wenn pcchPathListLength null ist.

[in, out] pcchPathListLength

Größe des mszExpandedPathList- Puffers in TCHARs-. Wenn null für eingaben 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 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.

Note You must add one to the required size on Windows XP.
 

[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 nicht den Namen der Instanz, wenn der Pfad ein Wildcardzeichen für die übergeordnete Instanz, den Instanznamen oder den Instanzindex 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 mszExpandedPathList Puffer ist nicht groß genug, 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.
PDH_INVALID_ARGUMENT
 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.
PDH_INVALID_PATH
 Das angegebene Objekt enthält keine Instanz.
PDH_MEMORY_ALLOCATION_FAILURE
 Speicher kann nicht zugewiesen werden, um diese Funktion zu unterstützen.
PDH_CSTATUS_NO_OBJECT
 Das angegebene Objekt auf dem Computer oder in der Protokolldatei konnte nicht gefunden werden.

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.

PdhExpandWildCardPath unterscheidet sich von PdhExpandCounterPath auf folgende Weise:

  1. Hiermit können Sie steuern, welche Wildcardzeichen erweitert werden.
  2. Der Inhalt einer Protokolldatei kann als Quelle von Leistungsindikatornamen verwendet werden.
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.

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
Verwenden Sie ein Sternchen (*) als Platzhalterzeichen, z. B. \object(*)\counter.

Wenn ein Wildcardzeichen im übergeordneten Namen angegeben ist, werden alle Instanzen des angegebenen Objekts zurückgegeben, die mit der angegebenen Instanz und den Zählerfeldern übereinstimmen. Beispiel: \object(*/instance)\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. Beispiel: \object(parent/*)\counter. Wenn das Objekt keine Instanz enthält, tritt ein Fehler auf.

Wenn ein Wildcardzeichen im Zählernamen angegeben ist, werden alle Zähler des angegebenen Objekts zurückgegeben.

Teilzählerpfadzeichenfolgen-Übereinstimmungen (z. B. "pro*") werden unterstützt.

Vor Windows Vista: Partielle Wildcard-Übereinstimmungen werden nicht unterstützt.

Anmerkung

Der pdh.h-Header definiert PdhExpandWildCardPath 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 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

Siehe auch

PdhEnumObjectItems

PdhEnumObjects

PdhExpandCounterPath

PdhExpandWildCardPathH