Метод IWbemClassObject::P ut (wbemcli.h)

Статья
08/27/2023

Метод IWbemClassObject::P ut задает для именованного свойства новое значение. Этот метод всегда перезаписывает текущее значение новым. Когда IWbemClassObject указывает на определение класса CIM, Put создает или обновляет значение свойства. Если IWbemClassObject указывает на экземпляр CIM, параметр 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 или указывает на VARIANT типа VT_NULL, свойство имеет значение NULL, то есть не имеет значения.

[in] Type

Тип VARIANT , на который указывает pVal.

Значение NULL для свойства, обозначенного variant с типом VT_NULL , отличается от свойства типа VT_I4 со значением 0 (ноль).

Если при создании новых свойств pVal имеет значение NULL или указывает на VT_NULL, тип свойства определяется из параметра vtType .

Если pVal должен содержать внедренный объект IWbemClassObject, вызывающий объект должен вызвать IWbemClassObject::QueryInterface для IID_IUnknown и поместить полученный указатель в VARIANT с помощью типа VT_UNKNOWN. Исходный внедренный объект копируется во время операции Put и поэтому не может быть изменен операцией.

Указатель обрабатывается как доступный только для чтения. После завершения этого вызова вызывающий объект должен вызвать VariantClear .

Используйте этот параметр только при создании новых свойств в определении класса CIM, а pVal имеет значение NULL или указывает на VARIANT типа VT_NULL. В этом случае параметр vtType указывает тип CIM свойства . Во всех остальных случаях vtType должен иметь значение 0 (ноль). Кроме того, значение vtType должно иметь значение 0 (ноль), если базовый объект является экземпляром (даже если pVal имеет значение NULL), так как тип свойства является фиксированным и не может быть изменен. Иными словами, используйте vtType , если и только в том случае, если pVal имеет значение NULL или указывает на VT_NULLVARIANT, а базовым объектом является класс CIM.

При использовании IWbemClassObject::P ut для назначения пустых значений массива свойству не нужно указывать точный тип VT; Вы можете присвоить значение pVal , которое является VARIANT с типом variant VT_ARRAY|VT_VARIANT.

Возвращаемое значение

Этот метод возвращает HRESULT , указывающий состояние вызова метода. В следующем списке перечислены значения, содержащиеся в HRESULT. Общие значения HRESULT см. в разделе Системные коды ошибок.

Если свойство, заданное методом IWbemClassObject::P ut , существует в родительском классе, значение свойства по умолчанию изменяется, если тип свойства не соответствует типу родительского класса. Если свойство не существует и не является несоответствием типов, создается свойство .

При выполнении этого метода в экземпляре всегда происходит перезапись, так как свойство всегда существует.

При создании нового класса и базовым типом свойства является ссылка на объект, строка даты и времени или другой специальный тип, может потребоваться изменить параметр типа CIM для свойства, чтобы указать специальный новый класс. Квалификатор CIMType в свойствах экземпляра доступен только для чтения и наследуется от объекта класса .

Если тип варианта, указанный в pVal , не соответствует типу CIM свойства, WMI пытается изменить вариант на соответствующий тип варианта, используя правила приведения обычных вариантов. Если вариант не может быть приведен, возвращается WBEM_E_TYPE_MISMATCH . В следующем списке перечислены исключения из правил приведения обычных вариантов, если свойство имеет тип uint32.

Передача типа variant	Результат
VT_I4	S_OK
VT_I2	WBEM_TYPE_MISMATCH
VT_R8	S_OK Однако передача VT_R8 VT_ARRAY\| в свойство типа 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
Header	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