Метод IWbemClassObject::P ut (wbemcli.h)
Метод 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 |