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 が含まれている場合、呼び出し元は IWbemClassObject::QueryInterface を呼び出してIID_IUnknownを呼び出し、結果のポインターをバリアント型の 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 型を指定する必要はありません。バリアント型がVT_VARIANT のバリアント型である pVal に値VT_ARRAY|割り当てることができます。

戻り値

このメソッドは、メソッド呼び出しの状態を示す 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 ただし、uint32[] 型のプロパティにVT_ARRAY\|VT_R8を渡すと失敗します。

__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 値は 16 進数ではなく 10 進形式である必要があることに注意してください。

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