PdhAddEnglishCounterA-Funktion (pdh.h)

Artikel
11/20/2024

Fügt der Abfrage den angegebenen sprachneutralen Zähler hinzu.

Syntax

PDH_FUNCTION PdhAddEnglishCounterA(
  [in]  PDH_HQUERY   hQuery,
  [in]  LPCSTR       szFullCounterPath,
  [in]  DWORD_PTR    dwUserData,
  [out] PDH_HCOUNTER *phCounter
);

Parameter

[in] hQuery

Behandeln Sie die Abfrage, der Sie den Zähler hinzufügen möchten. Dieses Handle wird von der PdhOpenQuery--Funktion zurückgegeben.

[in] szFullCounterPath

Null-beendete Zeichenfolge, die den Zählerpfad enthält. Ausführliche Informationen zum Format eines Zählerpfads finden Sie unter Angeben eines Zählerpfads. Die maximale Länge eines Zählerpfads ist PDH_MAX_COUNTER_PATH.

[in] dwUserData

Benutzerdefinierter Wert. Dieser Wert wird Teil der Leistungsindikatorinformationen. Rufen Sie zum späteren Abrufen dieses Werts die PdhGetCounterInfo-Funktion auf, und greifen Sie auf das dwQueryUserData- element der PDH_COUNTER_INFO-Struktur zu.

[out] phCounter

Behandeln Sie den Leistungsindikator, der der Abfrage hinzugefügt wurde. Möglicherweise müssen Sie in nachfolgenden Aufrufen auf dieses Handle verweisen.

Rückgabewert

Gibt ERROR_SUCCESS zurück, wenn die Funktion erfolgreich ist.

Wenn die Funktion fehlschlägt, ist der Rückgabewert ein Systemfehlercode oder ein PDH-Fehlercode. Im Folgenden sind mögliche Werte aufgeführt.

Rückgabecode	Beschreibung
PDH_CSTATUS_BAD_COUNTERNAME	Der Zählerpfad konnte nicht analysiert oder interpretiert werden.
PDH_CSTATUS_NO_COUNTER	Der angegebene Zähler auf dem Computer oder in der Protokolldatei konnte nicht gefunden werden.
PDH_CSTATUS_NO_COUNTERNAME	Der Zählerpfad ist leer.
PDH_CSTATUS_NO_MACHINE	Der Pfad enthielt keinen Computernamen, und die Funktion konnte den lokalen Computernamen nicht abrufen.
PDH_CSTATUS_NO_OBJECT	Das angegebene Objekt auf dem Computer oder in der Protokolldatei konnte nicht gefunden werden.
PDH_FUNCTION_NOT_FOUND	Die Berechnungsfunktion, die für diesen Leistungsindikator verwendet werden soll, kann nicht ermittelt werden.
PDH_INVALID_ARGUMENT	Mindestens ein Argument ist ungültig.
PDH_INVALID_HANDLE	Das Abfragehandle ist ungültig.
PDH_MEMORY_ALLOCATION_FAILURE	Speicher, der zum Abschließen der Funktion erforderlich ist, kann nicht zugeordnet werden.

Bemerkungen

Diese Funktion bietet eine sprachneutrale Methode zum Hinzufügen von Leistungsindikatoren zur Abfrage. Im Gegensatz dazu muss der Zählerpfad, den Sie im PdhAddCounter--Funktion angeben, lokalisiert werden.

Wenn eine Zählerinstanz angegeben ist, die noch nicht vorhanden ist, meldet PdhAddEnglishCounter keine Fehlerbedingung. Stattdessen wird ERROR_SUCCESS zurückgegeben. Der Grund für dieses Verhalten ist, dass es nicht bekannt ist, ob eine nicht vorhandene Zählerinstanz angegeben wurde oder ob eine vorhanden ist, aber noch nicht erstellt wurde.

Um den Zähler aus der Abfrage zu entfernen, verwenden Sie die PdhRemoveCounter--Funktion.

Hinweis Wenn der Zählerpfad ein Wildcardzeichen enthält, werden die Nicht-Wildcard-Teile des Pfads lokalisiert, aber die Wildcards werden nicht erweitert, bevor der lokalisierte Zählerpfad zur Abfrage hinzugefügt wird. In diesem Fall benötigen Sie das folgende Verfahren, um der Abfrage alle übereinstimmenden Zählernamen hinzuzufügen.

Erstellen einer Abfrage
Verwenden von PdhAddEnglishCounter- mit der Zeichenfolge, die Wildcards enthält
Verwenden Sie PdhGetCounterInfo- auf dem Zählerhandle, das von PdhAddEnglishCounter zurückgegeben wird, um einen lokalisierten vollständigen Pfad abzurufen (szFullPath.) Diese Zeichenfolge enthält weiterhin Wildcards, aber die Nicht-Wildcard-Teile werden jetzt lokalisiert.
Verwenden Sie PdhExpandWildCardPath-, um die Wildcards zu erweitern.
Verwenden sie PdhAddCounter- auf jedem der resultierenden Pfade

Anmerkung

Der pdh.h-Header definiert PdhAddEnglishCounter 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 Vista [nur Desktop-Apps]
mindestens unterstützte Server-	Windows Server 2008 [Nur Desktop-Apps]
Zielplattform-	Fenster
Header-	pdh.h
Library	Pdh.lib
DLL-	Pdh.dll

Siehe auch

Freigeben über