IWbemClassObject::P ut-Methode (wbemcli.h)

Artikel
08/27/2023

Die IWbemClassObject::P ut-Methode legt eine benannte Eigenschaft auf einen neuen Wert fest. Diese Methode überschreibt immer den aktuellen Wert mit einem neuen Wert. Wenn IWbemClassObject auf eine CIM-Klassendefinition verweist, erstellt oder aktualisiert Put den Eigenschaftswert. Wenn IWbemClassObject auf eine CIM-instance verweist, aktualisiert Put nur einen Eigenschaftswert. Put kann keinen Eigenschaftswert erstellen.

Ein Benutzer kann keine Eigenschaften mit Namen erstellen, die mit einem Unterstrich (_) beginnen oder enden. Dies ist für Systemklassen und -eigenschaften reserviert.

Syntax

HRESULT Put(
  [in] LPCWSTR wszName,
  [in] long    lFlags,
  [in] VARIANT *pVal,
  [in] CIMTYPE Type
);

Parameter

[in] wszName

Ein Parameter, der auf einen gültigen Eigenschaftennamen verweisen muss. Dieser Parameter darf nicht NULL sein.

[in] lFlags

Reserviert. Dieser Parameter muss 0 (null) sein.

[in] pVal

Ein Parameter, der auf einen gültigen VARIANT-Wert verweisen muss, der zum neuen Eigenschaftswert wird. Wenn pValNULL ist oder auf einen VARIANT-Wert vom Typ VT_NULL verweist, wird die Eigenschaft auf NULL festgelegt, d. h. kein Wert.

[in] Type

Ein Variant-Typ , auf den pVal verweist.

Der NULL-Wert für eine Eigenschaft, die durch einen VARIANT-Wert vom Typ VT_NULL bezeichnet wird, unterscheidet sich von einer Eigenschaft vom Typ VT_I4 mit einem Wert von 0 (null).

Wenn beim Erstellen neuer Eigenschaften pValNULL ist oder auf eine VT_NULL zeigt, wird der Typ der Eigenschaft aus dem vtType-Parameter bestimmt.

Wenn pVal ein eingebettetes IWbemClassObject enthalten soll, muss der Aufrufer IWbemClassObject::QueryInterface für IID_IUnknown aufrufen und den resultierenden Zeiger mithilfe eines Typs von VT_UNKNOWN im VARIANT platzieren. Das ursprüngliche eingebettete Objekt wird während des Put-Vorgangs kopiert und kann daher nicht vom Vorgang geändert werden.

Der Zeiger wird als schreibgeschützt behandelt. Der Aufrufer muss VariantClear aufrufen, nachdem dieser Aufruf abgeschlossen ist.

Verwenden Sie diesen Parameter nur beim Erstellen neuer Eigenschaften in einer CIM-Klassendefinition, und pVal ist NULL oder zeigt auf einen VARIANT-TypVT_NULL. In einem solchen Fall gibt der vtType-Parameter den CIM-Typ der -Eigenschaft an. In jedem anderen Fall muss vtType 0 (null) sein. Außerdem muss vtType 0 (null) sein, wenn das zugrunde liegende Objekt ein instance ist (auch wenn pValNULL ist), da der Typ der Eigenschaft fest ist und nicht geändert werden kann. Anders ausgedrückt: Verwenden Sie vtType , wenn und nur, wenn pValNULL ist oder auf eine VT_NULLVARIANT verweist, und das zugrunde liegende Objekt ist eine CIM-Klasse.

Wenn Sie IWbemClassObject::P utut verwenden, um einer Eigenschaft leere Arraywerte zuzuweisen, müssen Sie den genauen VT-Typ nicht angeben. Sie können pVal einen Wert zuweisen, bei dem es sich um einen VARIANT-Wert mit dem Variantentyp VT_ARRAY|VT_VARIANT handelt.

Rückgabewert

Diese Methode gibt ein HRESULT zurück, das den Status des Methodenaufrufs angibt. In der folgenden Liste sind die Werte aufgeführt, die in einem HRESULT enthalten sind. Allgemeine HRESULT-Werte finden Sie unter Systemfehlercodes.

Hinweise

Wenn die von der IWbemClassObject::P ut-Methode festgelegte Eigenschaft in der übergeordneten Klasse vorhanden ist, wird der Standardwert der Eigenschaft geändert, es sei denn, der Eigenschaftentyp stimmt nicht mit dem übergeordneten Klassentyp überein. Wenn die Eigenschaft nicht vorhanden ist und kein Typkonflikt vorliegt, wird die Eigenschaft erstellt.

Beim Ausführen dieser Methode auf einem instance wird immer überschrieben, da die -Eigenschaft immer vorhanden ist.

Wenn Sie eine neue Klasse erstellen und der zugrunde liegende Typ der Eigenschaft ein Objektverweis, eine Datums-/Uhrzeitzeichenfolge oder ein anderer spezieller Typ ist, müssen Sie möglicherweise den CIM-Typparameter für die -Eigenschaft ändern, um die spezielle neue Klasse anzugeben. Der CIMType-Qualifizierer für instance Eigenschaften ist schreibgeschützt und wird vom Klassenobjekt geerbt.

Wenn der in pVal angegebene Variantentyp nicht mit dem CIM-Typ der Eigenschaft übereinstimmt, versucht WMI, die Variante mithilfe der normalen Variantenkoerzregeln in den entsprechenden Variantentyp zu ändern. Wenn die Variante nicht zwangsverwendet werden kann, wird WBEM_E_TYPE_MISMATCH zurückgegeben. In der folgenden Liste werden Ausnahmen von den regeln für die normale Variantenkoerz aufgelistet, wenn die Eigenschaft den Typ uint32 hat.

Übergeben des Variantentyps	Ergebnis
VT_I4	S_OK
VT_I2	WBEM_TYPE_MISMATCH
VT_R8	S_OK Das Übergeben eines VT_ARRAY\|VT_R8 an eine Eigenschaft vom Typ uint32[] schlägt jedoch fehl.

Die __CLASS Systemeigenschaft kann nur während der Klassenerstellung beschreibbar sein, wenn sie möglicherweise nicht leer bleibt. Alle anderen Systemeigenschaften sind schreibgeschützt.

Beispiele

Im folgenden Codebeispiel wird gezeigt, wie der Klassenname für eine neue CIM-Klasse festgelegt wird.

// pObj is an empty object from IWbemServices::GetObject
// Set up the property value.
VARIANT v; 
VariantInit(&v);
V_VT(&v) = VT_BSTR;
V_BSTR(&v) = SysAllocString(L"MyClass");

// Write it.
LPCWSTR strClassProp = L"__CLASS";
pObj->Put(strClassProp, 0, &v, 0);

// Clean up.
VariantClear(&v);

Im folgenden Codebeispiel wird veranschaulicht, wie der Wert der SomeUint64-Eigenschaft festgelegt wird. Beachten Sie, dass der BSTR-Wert im Dezimalformat und nicht hexadezimal sein muss.

// pObj is an instance containing a uint64 property
// Set up the property value.
VARIANT v; 
VariantInit(&v);
V_VT(&v) = VT_BSTR;
V_BSTR(&v) = SysAllocString(L"1033"); // - decimal format, not hex

// Write it.
LPCWSTR strClassProp = L"SomeUint64";
pObj->Put(strClassProp, 0, &v, CIM_UINT64);

// Clean up.
VariantClear(&v);

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows Vista
Unterstützte Mindestversion (Server)	Windows Server 2008
Zielplattform	Windows
Kopfzeile	wbemcli.h (include Wbemidl.h)
Bibliothek	WbemUuid.lib
DLL	CIMWin32.dll; Esscli.dll; Fastprox.dll; FrameDyn.dll; FrameDynOS.dll; Krnlprov.dll; Ncprov.dll; Wbemcore.dll; Wbemess.dll; Wmipiprt.dll