Метод IWbemServices::P utInstance (wbemcli.h)

Статья
03/03/2024

Метод IWbemServices::P utInstance создает или обновляет экземпляр существующего класса. Экземпляр записывается в репозиторий WMI.

Синтаксис

HRESULT PutInstance(
  [in]  IWbemClassObject *pInst,
  [in]  long             lFlags,
  [in]  IWbemContext     *pCtx,
  [out] IWbemCallResult  **ppCallResult
);

Параметры

[in] pInst

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

[in] lFlags

Можно задать одно или несколько следующих значений.

WBEM_FLAG_CREATE_OR_UPDATE

Этот флаг приводит к созданию экземпляра, если он не существует, или перезаписи, если он уже существует.

WBEM_FLAG_UPDATE_ONLY

Этот флаг вызывает обновление этого вызова. Экземпляр должен существовать, чтобы вызов был успешным.

WBEM_FLAG_CREATE_ONLY

Этот флаг используется только для создания. Вызов завершается ошибкой, если экземпляр уже существует.

WBEM_FLAG_RETURN_IMMEDIATELY

Этот флаг приводит к полусинхронному вызову. Дополнительные сведения см. в разделе Вызов метода.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Если этот флаг установлен, инструментарий WMI не сохраняет квалификаторы с измененным вкусом. Если этот флаг не задан, предполагается, что этот объект не локализован и все квалификаторы хранятся вместе с этим экземпляром.

[in] pCtx

Обычно имеет значение NULL, указывающее, что каждое свойство в экземпляре должно быть обновлено. В противном случае это указатель на объект IWbemContext , содержащий дополнительные сведения об экземпляре . Данные в объекте контекста должны быть задокументированы поставщиком, ответственным за экземпляр. Объект IWbemContext, отличный от NULL, может указывать, существует ли поддержка частичных обновлений экземпляров.

Дополнительные сведения о поддержке полных и частичных обновлений экземпляров см. в разделе IWbemServices::P utInstanceAsync. Дополнительные сведения о запросе полного или частичного обновления экземпляра см. в разделе Изменение свойства экземпляра.

[out] ppCallResult

Если значение РАВНО NULL, этот параметр не используется. Если параметр lFlags содержит WBEM_FLAG_RETURN_IMMEDIATELY, этот вызов немедленно возвращается с WBEM_S_NO_ERROR. Затем параметр ppCallResult получает указатель на новый объект IWbemCallResult , который можно опрашивать с помощью IWbemCallResult::GetCallStatus для получения результата.

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

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

Коды ошибок COM также могут возвращаться, если проблемы с сетью приводят к потере удаленного подключения к управлению Windows.

Приложения и поставщики вызывают PutInstance для создания или обновления экземпляра существующего класса. В зависимости от того, как задан параметр pCtx , обновляются некоторые или все свойства экземпляра. Дополнительные сведения о поддержке частичного обновления экземпляров см. в разделе IWbemServices::P utInstanceAsync. Дополнительные сведения о запросе частичного обновления экземпляра см. в разделе Изменение свойства экземпляра.

Метод PutInstance поддерживает создание экземпляров и обновление только экземпляров. Он не поддерживает перемещение экземпляров. Это значит, что вызывающий объект не может задать параметр pInst для экземпляра, который имеет ключ, аналогичный другому экземпляру в одноуровневом классе. Например, предположим, класс А является базовым классом для ClassB и ClassC. Класс ClassA определяет свойство KeyProp в качестве ключа, а класс ClassB имеет экземпляр с свойством KeyProp , равным 1. Чтобы создать экземпляр ClassC с параметром KeyProp , равным 1, приложение должно сначала удалить экземпляр ClassB , вызвав DeleteInstance , а затем сохранить экземпляр ClassC с помощью PutInstance.

Если экземпляр, на который указывает pInst , принадлежит к подклассу, управление Windows вызывает все поставщики, отвечающие за классы, от которых наследуется подкласс. Все эти поставщики должны быть успешными, чтобы исходный запрос PutInstance был успешным. Первым вызывается поставщик, поддерживающий самый верхний класс в иерархии. Порядок вызовов продолжается с подклассом верхнего класса и продолжается сверху вниз, пока управление Windows не достигнет поставщика для класса, владеющего экземпляром, на который указывает pInst.

Управление Windows не вызывает поставщиков ни для одного из дочерних классов экземпляра. Таким образом, если приложение хочет изменить значения унаследованных свойств, оно должно вызывать Метод PutInstance для полного экземпляра дочернего класса, а не соответствующего экземпляра родительского класса.

Когда приложению необходимо обновить экземпляр, принадлежащий иерархии классов, параметр pInst должен указывать на экземпляр, содержащий свойства, которые необходимо изменить. То есть рассмотрим целевой экземпляр, принадлежащий классуB. Экземпляр ClassB является производным от ClassA, а Класс А определяет свойство PropA. Если приложение хочет изменить значение PropA в экземпляре ClassB , оно должно задать для pInst значение этого экземпляра, а не экземпляра Класса А.

Вызов PutInstance для экземпляра абстрактного класса не допускается.

Требования

Требование	Значение
Минимальная версия клиента	Windows Vista
Минимальная версия сервера	Windows Server 2008
Целевая платформа	Windows
Header	wbemcli.h (включая Wbemidl.h)
Библиотека	Wbemuuid.lib
DLL	Fastprox.dll; Esscli.dll; FrameDyn.dll; FrameDynOS.dll; Ntevt.dll; Stdprov.dll; Viewprov.dll; Wbemcomn.dll; Wbemcore.dll; Wbemess.dll; Wbemsvc.dll; Wmipicmp.dll; Wmidcprv.dll; Wmipjobj.dll; Wmiprvsd.dll