IWbemClassObject：:P ut 方法 (wbemcli.h)

项目
08/27/2023

IWbemClassObject：:P ut 方法将命名属性设置为新值。此方法始终使用新值覆盖当前值。当 IWbemClassObject 指向 CIM 类定义时， Put 将创建或更新属性值。当 IWbemClassObject 指向 CIM 实例时， Put 仅更新属性值。 Put 无法创建属性值。

用户无法创建名称以下划线 (_) 开头或结尾的属性。此为系统类和属性保留。

语法

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

参数

[in] wszName

一个必须指向有效属性名称的参数。此参数不能为 NULL。

[in] lFlags

保留。此参数必须为 0 (零) 。

[in] pVal

一个必须指向有效 VARIANT 的参数，该变量将成为新的属性值。如果 pVal 为 NULL 或指向类型为 VT_NULL 的 VARIANT，则属性设置为 NULL，即无值。

[in] Type

pVal 指向的 VARIANT 类型。

VT_NULL 类型的VARIANT 指定的属性的 NULL 值与) 值为 0 (零的 VT_I4 类型的属性进行区分。

创建新属性时，如果 pVal 为 NULL 或指向 VT_NULL，则属性的类型由 vtType 参数确定。

如果 pVal 要包含嵌入的 IWbemClassObject，则调用方必须为IID_IUnknown调用 IWbemClassObject：：QueryInterface，并使用VT_UNKNOWN类型将生成的指针放在 VARIANT 中。原始嵌入对象在 Put 操作期间复制，因此无法由操作修改。

指针被视为只读。调用方必须在此调用完成后调用 VariantClear 。

仅当在 CIM 类定义中创建新属性且 pVal 为 NULL 或指向类型为 VT_NULL 的 VARIANT 时，才使用此参数。在这种情况下， vtType 参数指定属性的 CIM 类型。在所有其他情况下， vtType 必须为 0 (零) 。此外，当基础对象是实例 (即使 pVal) 为 NULL 时，vtType 必须为 0 (零) ，因为属性的类型是固定的且无法更改。换句话说，仅当 pVal 为 NULL 或指向 VT_NULLVARIANT 且基础对象为 CIM 类时，才使用 vtType。

使用 IWbemClassObject：:P ut 将空数组值分配给属性时，无需指定确切的 VT 类型;可以为 pVal 赋值，该值是 variant 类型为 VT_ARRAY|VT_VARIANT。

返回值

此方法返回指示方法调用状态的 HRESULT。以下列表列出了 HRESULT 中包含的值。有关常规 HRESULT 值，请参阅系统错误代码。

注解

如果父类中存在 IWbemClassObject：:P ut 方法设置的属性，则属性的默认值将更改，除非属性类型与父类类型不匹配。如果该属性不存在，且并非类型不匹配，则创建该属性。

在实例上执行此方法时，始终会发生覆盖，因为属性始终存在。

创建新类并且属性的基础类型是对象引用、日期/时间字符串或其他特殊类型时，可能需要修改属性的 CIM 类型参数以指示特殊的新类。实例属性上的 CIMType 限定符是只读的，从类对象继承。

如果 pVal 中指定的变体类型与属性的 CIM 类型不匹配，则 WMI 会尝试使用正常变体强制规则将变体更改为适当的变体类型。如果变量无法强制，则返回 WBEM_E_TYPE_MISMATCH 。以下列表列出了当属性类型为 uint32 时，常规变体强制规则的例外。

传入变体类型	结果
VT_I4	S_OK
VT_I2	WBEM_TYPE_MISMATCH
VT_R8	S_OK 但是，将 VT_ARRAY\|VT_R8 传递到 uint32[] 类型的属性将失败。

__CLASS系统属性仅在类创建期间不可写，但不能留空。所有其他系统属性均为只读。

示例

下面的代码示例演示如何设置新 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);

下面的代码示例演示如何设置 SomeUint64 属性的值。请注意， BSTR 值必须采用十进制格式，而不是十六进制。

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

要求

要求	值
最低受支持的客户端	Windows Vista
最低受支持的服务器	Windows Server 2008
目标平台	Windows
标头	wbemcli.h (包括 Wbemidl.h)
Library	WbemUuid.lib
DLL	CIMWin32.dll;Esscli.dll;Fastprox.dll;FrameDyn.dll;FrameDynOS.dll;Krnlprov.dll;Ncprov.dll;Wbemcore.dll;Wbemess.dll;Wmipiprt.dll