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 的参数,该 变量将成为新的属性值。 如果 pValNULL 或指向类型为 VT_NULLVARIANT,则 属性设置为 NULL,即无值。

[in] Type

pVal 指向的 VARIANT 类型。

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

创建新属性时,如果 pValNULL 或指向 VT_NULL,则属性的类型由 vtType 参数确定。

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

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

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

另请参阅

IUnknown::QueryInterface

IWbemClassObject

WMI 限定符

WMI 系统类

WMI 系统属性