IWbemClassObject::P ut 方法 (wbemcli.h)
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 |