IWbemClassObject ::P ut, méthode (wbemcli.h)

Article
03/06/2024

La méthode IWbemClassObject ::P ut affecte une nouvelle valeur à une propriété nommée. Cette méthode remplace toujours la valeur actuelle par une nouvelle. Quand IWbemClassObject pointe vers une définition de classe CIM, Put crée ou met à jour la valeur de la propriété. Quand IWbemClassObject pointe vers un instance CIM, Put met à jour une valeur de propriété uniquement. Put ne peut pas créer de valeur de propriété.

Un utilisateur ne peut pas créer de propriétés dont les noms commencent ou se terminent par un trait de soulignement (_). Cela est réservé aux classes et aux propriétés système.

Syntaxe

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

Paramètres

[in] wszName

Paramètre qui doit pointer vers un nom de propriété valide. Ce paramètre ne peut pas être NULL.

[in] lFlags

Réservé. Ce paramètre doit être égal à 0 (zéro).

[in] pVal

Paramètre qui doit pointer vers un VARIANT valide, qui devient la nouvelle valeur de propriété. Si pVal a la valeur NULL ou pointe vers un VARIANT de type VT_NULL, la propriété a la valeur NULL, c’est-à-dire aucune valeur.

[in] Type

Type de VARIANT pointé vers pVal.

La valeur NULL d’une propriété désignée par un VARIANT de type VT_NULL se distingue d’une propriété de type VT_I4 avec une valeur 0 (zéro).

Lors de la création de propriétés, si pVal a la valeur NULL ou pointe vers un VT_NULL, le type de la propriété est déterminé à partir du paramètre vtType .

Si pVal doit contenir un IWbemClassObject incorporé, l’appelant doit appeler IWbemClassObject ::QueryInterface pour IID_IUnknown et placer le pointeur résultant dans le VARIANT à l’aide d’un type de VT_UNKNOWN. L’objet incorporé d’origine est copié pendant l’opération Put et ne peut donc pas être modifié par l’opération.

Le pointeur est traité en lecture seule. L’appelant doit appeler VariantClear une fois cet appel terminé.

Utilisez ce paramètre uniquement lors de la création de propriétés dans une définition de classe CIM et que pVal a la valeur NULL ou pointe vers un VARIANT de type VT_NULL. Dans ce cas, le paramètre vtType spécifie le type CIM de la propriété . Dans tous les autres cas, vtType doit être égal à 0 (zéro). En outre, vtType doit être égal à 0 (zéro) lorsque l’objet sous-jacent est un instance (même si pVal a la valeur NULL), car le type de la propriété est fixe et ne peut pas être modifié. En d’autres termes, utilisez vtType si, et uniquement si, pVal a la valeur NULL ou pointe vers un VT_NULLVARIANT et que l’objet sous-jacent est une classe CIM.

Lorsque vous utilisez IWbemClassObject ::P ut pour affecter des valeurs de tableau vides à une propriété, vous n’avez pas besoin de spécifier le type VT exact ; vous pouvez affecter à pVal une valeur qui est un VARIANT avec un type variant de VT_ARRAY|VT_VARIANT.

Valeur retournée

Cette méthode retourne une valeur HRESULT qui indique l’état de l’appel de méthode. La liste suivante répertorie les valeurs contenues dans un HRESULT. Pour connaître les valeurs HRESULT générales, consultez Codes d’erreur système.

Remarques

Si la propriété définie par la méthode IWbemClassObject ::P ut existe dans la classe parente, la valeur par défaut de la propriété est modifiée, sauf si le type de propriété ne correspond pas au type de classe parent. Si la propriété n’existe pas et s’il n’y a pas d’incompatibilité de types, la propriété est créée.

Lors de l’exécution de cette méthode sur un instance, un remplacement se produit toujours, car la propriété existe toujours.

Lorsque vous créez une classe et que le type sous-jacent de la propriété est une référence d’objet, une chaîne de date/heure ou un autre type spécial, vous devrez peut-être modifier le paramètre de type CIM de la propriété afin d’indiquer la nouvelle classe spéciale. Le qualificateur CIMType sur instance propriétés est en lecture seule et hérité de l’objet de classe.

Si le type de variant spécifié dans pVal ne correspond pas au type CIM de la propriété, WMI tente de remplacer la variante par le type de variant approprié, à l’aide des règles de forçage de variante normale. Si la variante ne peut pas être forcenée, WBEM_E_TYPE_MISMATCH est retournée. La liste suivante répertorie les exceptions aux règles de forçage de variante normale lorsque la propriété est de type uint32.

Passer le type de variante	Résultats
VT_I4	S_OK
VT_I2	WBEM_TYPE_MISMATCH
VT_R8	S_OK Toutefois, le passage d’une VT_ARRAY\|VT_R8 à une propriété de type uint32[] échoue.

La propriété système __CLASS n’est accessible en écriture que lors de la création de la classe, lorsqu’elle ne peut pas être laissée vide. Toutes les autres propriétés système sont en lecture seule.

Exemples

L’exemple de code suivant montre comment définir le nom de la classe pour une nouvelle 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);

L’exemple de code suivant montre comment définir la valeur de la propriété SomeUint64. N’oubliez pas que la valeur BSTR doit être au format décimal et non hexadécimal.

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

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows Vista
Serveur minimal pris en charge	Windows Server 2008
Plateforme cible	Windows
En-tête	wbemcli.h (include Wbemidl.h)
Bibliothèque	WbemUuid.lib
DLL	CIMWin32.dll ; Esscli.dll ; Fastprox.dll ; FrameDyn.dll ; FrameDynOS.dll ; Krnlprov.dll ; Ncprov.dll ; Wbemcore.dll ; Wbemess.dll ; Wmipiprt.dll