Metodo IWbemClassObject::P ut (wbemcli.h)

Articolo
08/27/2023

Il metodo IWbemClassObject::P ut imposta una proprietà denominata su un nuovo valore. Questo metodo sovrascrive sempre il valore corrente con uno nuovo. Quando IWbemClassObject punta a una definizione di classe CIM, Put crea o aggiorna il valore della proprietà. Quando IWbemClassObject punta a un'istanza CIM, inserire aggiorna solo un valore della proprietà. Non è possibile creare un valore di proprietà.

Un utente non può creare proprietà con nomi che iniziano o terminano con un carattere di sottolineatura (_). Questa opzione è riservata alle classi di sistema e alle proprietà.

Sintassi

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

Parametri

[in] wszName

Parametro che deve puntare a un nome di proprietà valido. Questo parametro non può essere NULL.

[in] lFlags

Riservato. Questo parametro deve essere 0 (zero).

[in] pVal

Parametro che deve puntare a UN VALORE VARIANT valido, che diventa il nuovo valore della proprietà. Se pVal è NULL o punta a un valore VARIANT di tipo VT_NULL, la proprietà è impostata su NULL, ovvero nessun valore.

[in] Type

Tipo di VARIANT a cui fa riferimento pVal.

Il valore NULL per una proprietà designata da un tipo VARIANTVT_NULL è distinto da una proprietà di tipo VT_I4 con un valore 0 (zero).

Quando si creano nuove proprietà, se pVal è NULL o punta a un VT_NULL, il tipo della proprietà viene determinato dal parametro vtType .

Se pVal deve contenere un IWbemClassObject incorporato, il chiamante deve chiamare IWbemClassObject::QueryInterface per IID_IUnknown e posizionare il puntatore risultante in VARIANT usando un tipo di VT_UNKNOWN. L'oggetto incorporato originale viene copiato durante l'operazione Put e quindi non può essere modificato dall'operazione.

Il puntatore viene considerato di sola lettura. Il chiamante deve chiamare VariantClear dopo il completamento della chiamata.

Usare questo parametro solo quando si creano nuove proprietà in una definizione di classe CIM e pVal è NULL o punta a un tipo VARIANTdi tipo VT_NULL. In tal caso, il parametro vtType specifica il tipo CIM della proprietà. In ogni altro caso, vtType deve essere 0 (zero). VtType deve anche essere 0 (zero) quando l'oggetto sottostante è un'istanza (anche se pVal è NULL), perché il tipo della proprietà è fisso e non può essere modificato. In altre parole, usare vtType se e solo se pVal è NULL o punta a un VT_NULLVARIANT e l'oggetto sottostante è una classe CIM.

Quando si usa IWbemClassObject::P ut per assegnare valori di matrice vuoti a una proprietà, non è necessario specificare il tipo VT esatto; è possibile assegnare un valore a pVal con un tipo variant di VT_ARRAY VT_VARIANT|.

Valore restituito

Questo metodo restituisce un HRESULT che indica lo stato della chiamata al metodo. Nell'elenco seguente sono elencati i valori contenuti in un HRESULT. Per i valori HRESULT generali, vedere Codici di errore di sistema.

Commenti

Se la proprietà impostata dal metodo IWbemClassObject::P ut esiste nella classe padre, il valore predefinito della proprietà viene modificato a meno che il tipo di proprietà non corrisponda al tipo di classe padre. Se la proprietà non esiste e non è una mancata corrispondenza del tipo, la proprietà viene creata.

Quando si esegue questo metodo in un'istanza, si verifica sempre una sovrascrittura perché la proprietà esiste sempre.

Quando si crea una nuova classe e il tipo sottostante della proprietà è un riferimento a oggetti, una stringa di data/ora o un altro tipo speciale, potrebbe essere necessario modificare il parametro di tipo CIM per la proprietà per indicare la nuova classe speciale. Il qualificatore CIMType nelle proprietà dell'istanza è di sola lettura e ereditato dall'oggetto classe.

Se il tipo di variante specificato in pVal non corrisponde al tipo CIM della proprietà, WMI tenta di modificare la variante al tipo variant appropriato usando le normali regole di coercizione varianti. Se la variante non può essere coerced, viene restituita WBEM_E_TYPE_MISMATCH . Nell'elenco seguente sono elencate le eccezioni alle normali regole di coercizione varianti quando la proprietà è di tipo uint32.

Passare il tipo di variante	Risultato
VT_I4	S_OK
VT_I2	WBEM_TYPE_MISMATCH
VT_R8	S_OK Tuttavia, il passaggio di un VT_ARRAY VT_R8\| a una proprietà di tipo uint32[] avrà esito negativo.

La proprietà di sistema __CLASS è scrivibile solo durante la creazione della classe, quando potrebbe non essere lasciata vuota. Tutte le altre proprietà di sistema sono di sola lettura.

Esempio

Nell'esempio di codice seguente viene illustrato come impostare il nome della classe per una nuova classe CIM.

// 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);

Nell'esempio di codice seguente viene illustrato come impostare il valore della proprietà SomeUint64. Tenere presente che il valore BSTR deve essere in formato decimale e non esadecimale.

// 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);

Requisiti

Requisito	Valore
Client minimo supportato	Windows Vista
Server minimo supportato	Windows Server 2008
Piattaforma di destinazione	Windows
Intestazione	wbemcli.h (include Wbemidl.h)
Libreria	WbemUuid.lib
DLL	CIMWin32.dll; Esscli.dll; Fastprox.dll; FrameDyn.dll; FrameDynOS.dll; Krnlprov.dll; Ncprov.dll; Wbemcore.dll; Wbemess.dll; Wmipiprt.dll