PdhEnumObjectsHA-Funktion (pdh.h)

  • Artikel

Gibt eine Liste der Objekte zurück, die auf dem angegebenen Computer oder in der angegebenen Protokolldatei verfügbar sind.

Diese Funktion ist mit PdhEnumObjects identisch, mit der Ausnahme, dass sie die Verwendung von Handles für Datenquellen unterstützt.

Syntax

PDH_FUNCTION PdhEnumObjectsHA(
  [in]      PDH_HLOG hDataSource,
  [in]      LPCSTR   szMachineName,
  [out]     PZZSTR   mszObjectList,
  [in, out] LPDWORD  pcchBufferSize,
  [in]      DWORD    dwDetailLevel,
  [in]      BOOL     bRefresh
);

Parameter

[in] hDataSource

Handle an eine Datenquelle, die von der PdhBindInputDataSource-Funktion zurückgegeben wird.

[in] szMachineName

Null-beendete Zeichenfolge, die den Namen des Computers angibt, der zum Auflisten der Leistungsobjekte verwendet wird.

Fügen Sie die führenden Schrägstriche in den Computernamen ein, z. B. \Computername.

Wenn szDataSourceNULL ist, können Sie szMachineName auf NULL festlegen, um den lokalen Computer anzugeben.

[out] mszObjectList

Vom Aufrufer zugewiesener Puffer, der die Liste der Objektnamen empfängt. Jeder Objektname in dieser Liste wird durch ein NULL-Zeichen beendet. Die Liste wird mit zwei NULL-Abschlusszeichen beendet. Legen Sie auf NULL fest, wenn pcchBufferLength 0 ist.

[in, out] pcchBufferSize

Größe des mszObjectList-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.

Windows XP: Fügen Sie eins zur erforderlichen Puffergröße hinzu.

[in] dwDetailLevel

Detailebene der zurückzugebenden Leistungselemente. Alle Elemente, die die angegebene Detailebene oder weniger aufweisen, werden zurückgegeben (die Ebenen werden in zunehmender Reihenfolge aufgeführt). Dieser Parameter kann einen der folgenden Werte annehmen.

Wert Bedeutung
PERF_DETAIL_NOVICE
 Detailebene für Anfänger.
PERF_DETAIL_ADVANCED
 Erweiterte Benutzerdetails.
PERF_DETAIL_EXPERT
 Detailebene des Expertenbenutzers.
PERF_DETAIL_WIZARD
 Detailebene des System-Designers.

[in] bRefresh

Gibt an, ob die zwischengespeicherte Objektliste automatisch aktualisiert werden soll. Geben Sie einen der folgenden Werte an.

Wenn Sie diese Funktion zweimal aufrufen, um die Größe der Liste und ein zweites Mal die tatsächliche Liste abzurufen, legen Sie diesen Parameter für den ersten Aufruf auf TRUE und FALSE für den zweiten Aufruf fest. Wenn beide Aufrufe TRUE sind, gibt der zweite Aufruf möglicherweise auch PDH_MORE_DATA zurück, da sich die Objektdaten zwischen den Aufrufen möglicherweise geändert haben.

Wert Bedeutung
TRUE
 Der Objektcache wird automatisch aktualisiert, bevor die Objekte zurückgegeben werden.
FALSE
 Aktualisieren Sie den Cache nicht automatisch.

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. Im Folgenden sind mögliche Werte aufgeführt.

Rückgabecode Beschreibung
PDH_MORE_DATA
 Der MszObjectList-Puffer ist zu klein, um die Liste der Objekte aufzunehmen. Dieser Rückgabewert wird erwartet, wenn pcchBufferLength 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.
PDH_CSTATUS_NO_MACHINE
 Der angegebene Computer ist offline oder nicht verfügbar.
PDH_CSTATUS_NO_OBJECT
 Das angegebene Objekt konnte nicht gefunden werden.
PDH_INVALID_ARGUMENT
 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.

Hinweise

Sie sollten diese Funktion zweimal aufrufen, zum ersten Mal zum Abrufen der erforderlichen Puffergröße (festlegen von mszObjectList auf NULL und pcchBufferLength auf 0), und beim zweiten Mal, um die Daten abzurufen.

Hinweis

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

Anforderung Wert
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

PdhBindInputDataSource

PdhEnumObjectItemsH