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

Статья
03/08/2023

Метод IWbemServices::P utInstanceAsync асинхронно создает или обновляет экземпляр существующего класса. Подтверждение обновления или отчеты об ошибках предоставляются через интерфейс IWbemObjectSink , реализованный вызывающим объектом.

Синтаксис

HRESULT PutInstanceAsync(
  [in] IWbemClassObject *pInst,
  [in] long             lFlags,
  [in] IWbemContext     *pCtx,
  [in] IWbemObjectSink  *pResponseHandler
);

Параметры

[in] pInst

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

[in] lFlags

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

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

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

WBEM_FLAG_CREATE_OR_UPDATE

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

WBEM_FLAG_UPDATE_ONLY

Обновления существующего экземпляра.

WBEM_FLAG_CREATE_ONLY

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

WBEM_FLAG_SEND_STATUS

Этот флаг регистрирует в управлении Windows запрос на получение промежуточных отчетов о состоянии через реализацию IWbemObjectSink::SetStatus. Реализация поставщика должна поддерживать промежуточные отчеты о состоянии для этого флага, чтобы изменить поведение.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

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

[in] pCtx

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

[in] pResponseHandler

Указатель на реализацию вызывающего объекта IWbemObjectSink. Этот обработчик получает состояние этого вызова, когда он становится доступным с помощью метода IWbemObjectSink::SetStatus . Если возвращается какой-либо код ошибки, предоставленный указатель IWbemObjectSink не используется. Если возвращается WBEM_S_NO_ERROR , вызывается реализация IWbemObjectSink пользователя, чтобы указать результат операции. Управление Windows вызывает AddRef для указателя только в тех случаях, когда возвращается WBEM_S_NO_ERROR . В случаях, когда возвращается код ошибки, количество ссылок совпадает с числом ссылок при записи. Дополнительные сведения о том, как выполнять асинхронные вызовы, см. в разделе Вызов метода .

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

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

Обратите внимание, что если PutInstanceAsync возвращает WBEM_S_NO_ERROR, WMI ожидает результата от метода SetStatus обработчика ответа. WMI ожидает неограниченное время при локальном подключении или до истечения времени ожидания удаленного подключения.

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

Если экземпляр, на который указывает pInst, принадлежит к классу, который является производным от других классов, успех PutInstanceAsync зависит от успешности поставщиков, ответственных за родительские классы. Например, если pInst принадлежит классуB , а ClassB является производным от ClassA, вызов метода PutInstanceAsync , реализованный поставщиком classA , должен быть успешным, чтобы операция обновления в ClassB была успешной. Дополнительные сведения см. в разделе Примечания в IWbemServices::P utInstance.

При реализации поставщика экземпляра, если для свойства ключа экземпляра задано значение NULL, PutInstanceAsync должен выбрать значение, гарантированное уникальное в пределах класса . Когда WMI обслуживает запрос на обновление экземпляра со свойством ключа NULL , он внутренне создает GUID и назначает его свойству ключа. Кроме того, когда обновляемый экземпляр принадлежит дочернему классу, успех операции зависит от успешного вызова PutInstanceAsync к каждому из поставщиков, отвечающих за классы выше в иерархии. Не возвращайте WBEM_S_NO_ERROR , пока не убедитесь, что все остальные поставщики успешно работают. Дополнительные сведения см. в разделе IWbemServices::P utInstance.

Поставщики экземпляров, поддерживающие частичное обновление, должны проверка для существования значения контекста __PUT_EXTENSIONS. Системное значение контекста — это значение, определенное WMI для определенных значений, задается клиентским приложением и поддерживается поставщиком экземпляров. Интерфейс IWbemContext предоставляет доступ к системным и другим контекстным значениям, зависящим от поставщика. В следующем списке перечислены значения контекста, поддерживающие операции обновления частичного экземпляра.

Вызывается метод IWbemObjectSink::SetStatus , чтобы указать конец результирующих наборов. Он также может вызываться без промежуточных вызовов IWbemObjectSink::Указывает , возникают ли ошибки.

Так как обратный вызов может быть возвращен не на том же уровне проверки подлинности, который требуется клиенту, рекомендуется использовать полусинхронный режим вместо асинхронного взаимодействия. Если требуется асинхронное взаимодействие, см. статью Вызов метода .

Дополнительные сведения об использовании методов полусинхронно см. в разделах IWbemServices::P utInstance и Вызов метода.

Системное значение контекста	Описание
__PUT_EXTENSIONS (VT_BOOL)	Клиентское приложение задало одно или несколько других значений контекста системы, чтобы предоставить дополнительные сведения об операции обновления.
__PUT_EXT_STRICT_NULLS (VT_BOOL)	Поставщик экземпляра должен принудительно принудить параметр свойств VT_NULL при необходимости и вызвать ошибку при сбое.
__PUT_EXT_PROPERTIES (VT_ARRAY \| VT_BSTR)	Содержит список обновляемых свойств. Поставщик экземпляра должен игнорировать все остальные свойства.
__PUT_EXT_ATOMIC (VT_BOOL)	Все обновления должны быть выполнены успешно или поставщик экземпляров должен отменить изменения обратно. Частичного успеха не может быть.

При реализации поставщика экземпляров следует отвечать на свойство NULL в pCtx следующим образом:

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

Если pCtx не имеет значение NULL и указывает на допустимые сведения о контексте, вызывающее приложение запрашивает частичное обновление экземпляра. Как и раньше, поставщики экземпляров, которые не поддерживают частичное обновление экземпляров, должны завершить операцию сбоем, возвращая WBEM_E_PROVIDER_NOT_CAPABLE.

При реализации асинхронной операции асинхронная операция не будет завершена до тех пор, пока вы не освободите все операции AddRef, выполненные в pResponseHandler. Это происходит, даже если вы вызываете SetStatus в pResponseHander. Если происходит утечка pResponseHandler , все клиенты синхронизации или полусинхронизации также не завершаются и, возможно, перестают отвечать на запросы в зависимости от реализации.

Даже в катастрофических случаях необходимо освободить ссылки на несвязанные поставщики. Это связано с тем, что в случаях синхронизации и полусинхронизации служба WMI владеет реализацией pResponseHandler: даже если процесс несвязанного поставщика завершается, клиенты по-прежнему не отвечают.

Примеры

В следующем примере описывается структура PutInstanceAsync.

HRESULT CStdProvider::PutInstanceAsync( 
            /* [in] */ IWbemClassObject __RPC_FAR *pInst,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
   // You must implement the InstanceIsValid method
   // to check to see if the instance in the pInst variable
   // is valid.
   if (InstanceIsValid(lFlags, pInst)) 
   {
       return WBEM_S_NO_ERROR;
   }

   return WBEM_E_PROVIDER_NOT_CAPABLE;   
}

Требования


Минимальная версия клиента	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