GetNames-Funktion

Artikel
06/12/2023

Ruft eine Teilmenge oder alle Namen der Eigenschaften eines Objekts ab.

Hinweis

Diese API ist ausschließlich für die interne Verwendung vorgesehen. Sie ist nicht für die Verwendung im Entwicklercode vorgesehen.

Syntax

HRESULT GetNames (
   [in] int                 vFunc,
   [in] IWbemClassObject*   ptr,
   [in] LPCWSTR             wszQualifierName,
   [in] LONG                lFlags,
   [in] VARIANT*            pQualifierValue,
   [out] SAFEARRAY (BSTR)** pstrNames
);

Parameter

vFunc
[in] Dieser Parameter wird nicht verwendet.

ptr
[in] Ein Zeiger auf eine IWbemClassObject-Instanz.

wszQualifierName
[in] Ein Zeiger auf ein gültiges LPCWSTR-Element, das einen Qualifizierernamen angibt, der als Teil eines Filters fungiert. Weitere Informationen finden Sie im Abschnitt Hinweise. Dieser Parameter kann null sein.

lFlags
[in] Eine Kombination aus Bitfeldern. Weitere Informationen finden Sie im Abschnitt Hinweise.

pQualifierValue [in] Ein Zeiger auf eine gültige VARIANT-Struktur, die mit einem Filterwert initialisiert wird. Dieser Parameter kann null sein.

pstrNames
[out] Eine SAFEARRAY-Struktur, die Eigenschaftsnamen enthält. Beim Einstieg muss dieser Parameter immer ein Zeiger auf null sein. Weitere Informationen finden Sie im Abschnitt Bemerkungen.

Rückgabewert

Die folgenden von dieser Funktion zurückgegebenen Werte werden in der Headerdatei WbemCli.h definiert oder können als Konstanten im Code definiert werden:

Konstante	Wert	Beschreibung
`WBEM_E_FAILED`	0x80041001	Es ist ein allgemeiner Fehler aufgetreten.
`WBEM_E_INVALID_PARAMETER`	0x80041008	Mindestens ein Parameter ist ungültig, oder es wurde eine falsche Kombination aus Flags und Parametern angegeben.
`WBEM_E_OUT_OF_MEMORY`	0x80041006	Es ist nicht genügend Arbeitsspeicher verfügbar, um den Vorgang abzuschließen.
`WBEM_S_NO_ERROR`	0	Der Funktionsaufruf war erfolgreich.

Bemerkungen

Diese Funktion umschließt einen Aufruf der IWbemClassObject::GetNames-Methode.

Die zurückgegebenen Namen werden mit einer Kombination aus Flags und Parametern gesteuert. Die Funktion kann beispielsweise die Namen aller Eigenschaften oder nur die Namen der Schlüsseleigenschaften zurückgeben. Der primäre Filter wird im lFlags-Parameter angegeben, und die anderen Parameter variieren je nach diesem Parameter.

Die Flagwerte in lFlags sind Bitfelder.

Die Flags, die als lEnumFlags-Argument übergeben werden können, sind Bitfelder, die in der Headerdatei WbemCli.h definiert sind. Alternativ können sie als Konstanten in Ihrem Code definiert werden. Sie können ein Flag aus jeder Gruppe mit einem beliebigen Flag aus jeder anderen Gruppe kombinieren. Flags aus der gleichen Gruppe schließen sich jedoch gegenseitig aus.

Flags der Gruppe 1	Wert	Beschreibung
`WBEM_FLAG_ALWAYS`	0	Gibt alle Eigenschaftennamen zurück. `strQualifierName` und `pQualifierVal` werden nicht verwendet.
`WBEM_FLAG_ONLY_IF_TRUE`	1	Gibt nur Eigenschaften zurück, die über einen Qualifizierer mit dem Namen verfügen, der durch den `strQualifierName`-Parameter angegeben ist. Wenn dieses Flag verwendet wird, muss `strQualifierName` angegeben werden.
`WBEM_FLAG_ONLY_IF_FALSE`	2	Gibt nur Eigenschaften zurück, die über keinen Qualifizierer mit dem Namen verfügen, der durch den `strQualifierName`-Parameter angegeben ist. Wenn dieses Flag verwendet wird, muss `strQualifierName` angegeben werden.
`WBEM_FLAG_ONLY_IF_IDENTICAL`	3	Gibt nur Eigenschaften zurück, die über einen Qualifizierer mit dem Namen verfügen, der durch den `wszQualifierName`-Parameter angegeben ist, und außerdem einen Wert haben, der dem durch die `pQualifierVal`-Struktur angegebenen Wert entspricht. Wenn dieses Flag verwendet wird, müssen sowohl ein Qualifizierername (`wszQualifierName`) als auch ein Qualifiziererwert (`pQualifierValue`) angegeben werden.

Flags der Gruppe 2	Wert	Beschreibung
`WBEM_FLAG_KEYS_ONLY`	0x4	Gibt nur die Namen der Eigenschaften zurück, die die Schlüssel definieren.
`WBEM_FLAG_REFS_ONLY`	0x8	Gibt nur Eigenschaftsnamen zurück, bei denen es sich um Objektverweise handelt.

Flags der Gruppe 3	Wert	Beschreibung
`WBEM_FLAG_LOCAL_ONLY`	0x10	Gibt nur Eigenschaftsnamen zurück, die zur am häufigsten abgeleiteten Klasse gehören. Eigenschaften aus den übergeordneten Klassen werden ausgeschlossen.
`WBEM_FLAG_PROPAGATED_ONLY`	0x20	Gibt nur Eigenschaftsnamen zurück, die zu den übergeordneten Klassen gehören.
`WBEM_FLAG_SYSTEM_ONLY`	0x30	Gibt nur die Namen von Systemeigenschaften zurück.
`WBEM_FLAG_NONSYSTEM_ONLY`	0x40	Gibt nur die Namen systemfremder Eigenschaften zurück.

Die Funktion ordnet immer ein neues sicheres Array (SAFEARRAY) zu, wenn sie WBEM_S_NO_ERROR zurückgibt, und pstrNames ist immer so festgelegt, dass darauf gezeigt wird. Das zurückgegebene Array kann null Elemente enthalten, wenn keine Eigenschaften den angegebenen Filtern entsprechen. Wenn die Funktion einen anderen Wert als WBM_S_NO_ERROR zurückgibt, wird keine neue SAFEARRAY-Struktur zurückgegeben.

Anforderungen

Plattformen: Informationen finden Sie unter Systemanforderungen.

Header: WMINet_Utils.idl

.NET Framework-Versionen: Seit Version 4.7.2 verfügbar

Siehe auch

WMI und Leistungsindikatoren (Referenz zur nicht verwalteten API)

Freigeben über