GetNames-Funktion

  • Artikel

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