PdhEnumObjectItemsHW-Funktion (pdh.h)

  • Artikel

Gibt den Zähler des angegebenen Objekts und instance Namen zurück, die auf dem angegebenen Computer oder in der angegebenen Protokolldatei vorhanden sind.

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

Syntax

PDH_FUNCTION PdhEnumObjectItemsHW(
  [in]      PDH_HLOG hDataSource,
  [in]      LPCWSTR  szMachineName,
  [in]      LPCWSTR  szObjectName,
  [out]     PZZWSTR  mszCounterList,
  [in, out] LPDWORD  pcchCounterListLength,
  [out]     PZZWSTR  mszInstanceList,
  [in, out] LPDWORD  pcchInstanceListLength,
  [in]      DWORD    dwDetailLevel,
  [in]      DWORD    dwFlags
);

Parameter

[in] hDataSource

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

[in] szMachineName

Null-terminierte Zeichenfolge, die den Namen des Computers angibt, der den Zähler und instance Namen enthält, die Sie aufzählen möchten.

Schließen Sie die führenden Schrägstriche in den Computernamen ein, z. B. \Computername.

Wenn der szDataSource-ParameterNULL ist, können Sie szMachineName auf NULL festlegen, um den lokalen Computer anzugeben.

[in] szObjectName

Null-terminierte Zeichenfolge, die den Namen des Objekts angibt, dessen Zähler und instance Namen Sie aufzählen möchten.

[out] mszCounterList

Vom Aufrufer zugewiesener Puffer, der eine Liste von Null-Endungszählernamen empfängt, die vom angegebenen Objekt bereitgestellt werden. Die Liste enthält eindeutige Zählernamen. Die Liste wird durch zwei NULL-Zeichen beendet. Legen Sie auf NULL fest, wenn der parameter pcchCounterListLength null ist.

[in, out] pcchCounterListLength

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

[out] mszInstanceList

Vom Aufrufer zugewiesener Puffer, der eine Liste mit null beendeten instance Namen empfängt, die vom angegebenen Objekt bereitgestellt werden. Die Liste enthält eindeutige instance Namen. Die Liste wird durch zwei NULL-Zeichen beendet. Legen Sie auf NULL fest, wenn der parameter pcchInstanceListLength null ist.

[in, out] pcchInstanceListLength

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

Wenn das angegebene Objekt keine Variableninstanzen unterstützt, ist der zurückgegebene Wert null. Wenn das angegebene Objekt Variableninstanzen unterstützt, aber derzeit keine Instanzen aufweist, ist der zurückgegebene Wert 2. Dies entspricht der Größe einer leeren MULTI_SZ Listenzeichenfolge.

[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 Benutzer.
PERF_DETAIL_ADVANCED
 Erweiterte Benutzerdetails.
PERF_DETAIL_EXPERT
 Detailebene des Expertenbenutzers.
PERF_DETAIL_WIZARD
 Detailebene des System-Designers.

[in] dwFlags

Dieser Parameter muss null sein.

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. Die folgenden Werte sind möglich.

Rückgabecode Beschreibung
PDH_MORE_DATA
 Einer der Puffer ist zu klein, um die Liste der Namen zu enthalten. Dieser Rückgabewert wird erwartet, wenn pcchCounterListLength oder pcchInstanceListLength 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_MEMORY_ALLOCATION_FAILURE
 Speicher kann nicht zugewiesen werden, um diese Funktion zu unterstützen.
PDH_CSTATUS_NO_MACHINE
 Der angegebene Computer ist offline oder nicht verfügbar.
PDH_CSTATUS_NO_OBJECT
 Das angegebene Objekt konnte auf dem angegebenen Computer oder in der angegebenen Protokolldatei nicht gefunden werden.

Hinweise

Sie sollten diese Funktion zweimal aufrufen, beim ersten Mal, um die erforderliche Puffergröße abzurufen (legen Sie die Puffer auf NULL und die Größen auf 0 fest), und beim zweiten Mal, um die Daten abzurufen.

Aufeinander folgende Aufrufe dieser Funktion geben identische Listen von Indikatoren und Instanzen zurück, da PdhEnumObjectItemsH immer die Liste der Leistungsobjekte abfragt, die durch den letzten Aufruf von PdhEnumObjectsH oder PdhEnumObjectItemsH definiert wurden. Um die Liste der Leistungsobjekte zu aktualisieren, rufen Sie PdhEnumObjectsH mit dem bRefresh-FlagwertTRUE auf, bevor Sie PdhEnumObjectItemsH erneut aufrufen.

Die Reihenfolge der instance- und Zählernamen ist nicht festgelegt.

Hinweis

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

PdhEnumObjectsH