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

發行項
03/03/2024

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，呼叫端必須呼叫 IWbemClassObject：：QueryInterface for IID_IUnknown，並使用類型VT_UNKNOWN將產生的指標放在 VARIANT 中。原始內嵌物件會在 Put 作業期間複製，因此無法由作業修改。

指標會被視為唯讀。呼叫端必須在完成此呼叫之後呼叫 VariantClear 。

只有在 CIM 類別定義中建立新屬性，且 pVal 為 NULL，或指向類型為 VT_NULL 的 VARIANT 時，才使用此參數。在這種情況下， vtType 參數會指定屬性的 CIM 類型。在其他情況下， vtType 必須是 0 (零) 。此外，當基礎對像是 (實例時， vtType 必須是 0 (零) ，即使 pVal 是 NULL) ，因為屬性的類型是固定的且無法變更。換句話說，只有在 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)
程式庫	WbemUuid.lib
Dll	CIMWin32.dll;Esscli.dll;Fastprox.dll;FrameDyn.dll;FrameDynOS.dll;Krnlprov.dll;Ncprov.dll;Wbemcore.dll;Wbemess.dll;Wmipiprt.dll