Método IWbemServices::P utInstanceAsync (wbemcli.h)

Artículo
03/08/2023

El método IWbemServices::P utInstanceAsync crea o actualiza de forma asincrónica una instancia de una clase existente. La confirmación de actualización o el informe de errores se proporciona a través de la interfaz IWbemObjectSink implementada por el autor de la llamada.

Sintaxis

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

Parámetros

[in] pInst

Puntero a la instancia que se va a escribir en el repositorio WMI. El autor de la llamada no puede realizar suposiciones sobre el recuento de referencias al finalizar esta llamada.

[in] lFlags

Especifica si el autor de la llamada quiere que se cree la instancia si la instancia no existe actualmente.

Al implementar un proveedor de instancias, puede optar por admitir un número limitado de marcas en lFlags devolviendo WBEM_E_PROVIDER_NOT_CAPABLE.

Esta propiedad puede tener uno o varios de los valores siguientes.

WBEM_FLAG_CREATE_OR_UPDATE

Esta marca hace que esta instancia se cree si no existe o se sobrescribe si ya existe.

WBEM_FLAG_UPDATE_ONLY

Novedades una instancia existente.

WBEM_FLAG_CREATE_ONLY

Esta marca es solo para la creación de instancias. Se produce un error en la llamada si la clase ya existe.

WBEM_FLAG_SEND_STATUS

Esta marca registra con administración de Windows una solicitud para recibir informes de estado intermedios a través de la implementación de clientes de IWbemObjectSink::SetStatus. La implementación del proveedor debe admitir informes de estado intermedios para que esta marca cambie el comportamiento.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Si se establece esta marca, WMI no almacena ningún calificador con el sabor modificado . Si no se establece esta marca, se supone que este objeto no está localizado y todos los calificadores se almacenan con esta instancia.

[in] pCtx

Puntero que describe si el cliente solicita una actualización parcial de la instancia o una actualización de instancia completa. Una actualización de instancia parcial modifica un subconjunto de las propiedades de la instancia. En cambio, una actualización de instancia completa modifica todas las propiedades. Si es NULL, este parámetro indica que la aplicación que llama está solicitando una actualización de instancia completa. De lo contrario, se trata de un puntero a un objeto IWbemContext requerido por el proveedor de clases dinámicas que genera las instancias de clase. Para obtener más información sobre este parámetro, vea Realizar llamadas a WMI.

[in] pResponseHandler

Puntero a la implementación del autor de la llamada de IWbemObjectSink. Este controlador recibe el estado de esta llamada cuando está disponible mediante el método IWbemObjectSink::SetStatus . Si se devuelve algún código de error, no se usa el puntero IWbemObjectSink proporcionado. Si se devuelve WBEM_S_NO_ERROR , se llama a la implementación IWbemObjectSink del usuario para indicar el resultado de la operación. Administración de Windows solo llama a AddRef en el puntero en los casos en los que WBEM_S_NO_ERROR devuelve. En los casos en los que se devuelve un código de error, el recuento de referencias es el mismo que en la entrada. Para obtener más información sobre cómo realizar llamadas asincrónicas, vea Llamar a un método.

Valor devuelto

Este método devuelve un valor HRESULT que indica el estado de la llamada al método. En la lista siguiente se muestra el valor contenido en un HRESULT.

Tenga en cuenta que si PutInstanceAsync devuelve WBEM_S_NO_ERROR, WMI espera un resultado del método SetStatus del controlador de respuesta. WMI espera indefinidamente en una conexión local o hasta que se agote el tiempo de espera de una conexión remota.

También se pueden devolver códigos de error específicos de COM si los problemas de red hacen que pierda la conexión remota a la administración de Windows.

Comentarios

Los clientes que llaman a PutInstanceAsync siempre deben esperar que se notifiquen los resultados de la llamada mediante su método IWbemObjectSink::Indicate .

Cuando la instancia a la que apunta pInst pertenece a una clase derivada de otras clases, el éxito de PutInstanceAsync depende del éxito de los proveedores responsables de las clases primarias. Por ejemplo, si pInst pertenece a ClassB y ClassB deriva de ClassA, una llamada al método PutInstanceAsync implementado por el proveedor para ClassA debe realizarse correctamente para que la operación de actualización de ClassB se realice correctamente. Para obtener más información, vea Comentarios en IWbemServices::P utInstance.

Al implementar un proveedor de instancias, si la instancia tiene una propiedad de clave establecida en NULL, PutInstanceAsync debe elegir un valor garantizado como único dentro de la clase . Cuando WMI atiende una solicitud para actualizar una instancia con una propiedad de clave NULL , genera internamente un GUID y lo asigna a la propiedad de clave. Además, cuando la instancia que se actualiza pertenece a una clase secundaria, el éxito de la operación depende del éxito de una llamada PutInstanceAsync a cada uno de los proveedores responsables de las clases superiores en la jerarquía. No devuelva WBEM_S_NO_ERROR hasta que esté seguro de que todos los demás proveedores se hayan realizado correctamente. Para obtener más información, vea IWbemServices::P utInstance.

Los proveedores de instancias que admiten una actualización parcial deben comprobar la existencia del valor de contexto de __PUT_EXTENSIONS . Un valor de contexto del sistema es un valor definido por WMI para tener significados específicos, se establece mediante la aplicación cliente y es compatible con un proveedor de instancias. La interfaz IWbemContext proporciona acceso a los valores de contexto del sistema y a otros valores de contexto específicos del proveedor. En la lista siguiente se enumeran los valores de contexto que admiten operaciones de actualización parcial de instancias.

Se llama al método IWbemObjectSink::SetStatus para indicar el final del conjunto de resultados. También se puede llamar sin llamadas intermedias a IWbemObjectSink::Indicar si se producen condiciones de error.

Dado que es posible que la devolución de llamada no se devuelva en el mismo nivel de autenticación que requiere el cliente, se recomienda usar la semisynchronous en lugar de la comunicación asincrónica. Si necesita comunicación asincrónica, consulte Llamar a un método.

Para obtener más información sobre el uso de métodos de forma semiincrónica, vea IWbemServices::P utInstance y Llamada a un método.

Valor de contexto del sistema	Descripción
__PUT_EXTENSIONS (VT_BOOL)	La aplicación cliente ha establecido uno o varios de los otros valores de contexto del sistema para proporcionar más información sobre la operación de actualización.
__PUT_EXT_STRICT_NULLS (VT_BOOL)	El proveedor de instancias debe forzar la configuración de las propiedades a VT_NULL cuando corresponda y generar un error en caso de error.
__PUT_EXT_PROPERTIES (VT_ARRAY \| VT_BSTR)	Contiene una lista de las propiedades que se van a actualizar. El proveedor de instancias debe omitir todas las demás propiedades.
__PUT_EXT_ATOMIC (VT_BOOL)	Todas las actualizaciones deben realizarse correctamente o el proveedor de instancias debe revertirse. No puede haber un éxito parcial.

Al implementar un proveedor de instancias, debe responder a una propiedad NULL de pCtx de la siguiente manera:

Si el tipo de propiedad es VT_NULL, el proveedor puede omitir la propiedad sin realizar un cambio o producir un error en la operación.
Si el tipo de propiedad no es VT_NULL y la propiedad no se puede actualizar, el proveedor debe devolver un error, ya que el proveedor está obligado a actualizar la propiedad con el nuevo valor.

Si pCtx no es NULL y apunta a información de contexto válida, la aplicación que llama solicita una actualización parcial de la instancia. Como antes, los proveedores de instancias que no admiten la actualización parcial de instancias deben producir un error en la operación devolviendo WBEM_E_PROVIDER_NOT_CAPABLE.

Al implementar una operación asincrónica, la operación asincrónica no se completa hasta que libere las addRef que haya realizado en pResponseHandler. Este es el caso incluso si llama a SetStatus en pResponseHander. Si se filtra pResponseHandler , los clientes de sincronización o semi-sincronización tampoco se completarán y posiblemente dejarán de responder, en función de la implementación.

Incluso en casos catastróficos, debe liberar las referencias para proveedores desacoplados. Esto se debe a que en los casos de sincronización y semiincronización, el servicio WMI posee la implementación de pResponseHandler: incluso si el proceso del proveedor desacoplado se cierra, los clientes no seguirán respondiendo.

Ejemplos

En el ejemplo siguiente se describe cómo estructurar 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;   
}

Requisitos


Cliente mínimo compatible	Windows Vista
Servidor mínimo compatible	Windows Server 2008
Plataforma de destino	Windows
Encabezado	wbemcli.h (include Wbemidl.h)
Library	Wbemuuid.lib
Archivo 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