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

Artículo
08/27/2023

El método IWbemServices::P utInstance crea o actualiza una instancia de una clase existente. La instancia se escribe en el repositorio de la WMI.

Sintaxis

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

Parámetros

[in] pInst

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

[in] lFlags

Se pueden establecer uno o varios de los valores siguientes.

WBEM_FLAG_CREATE_OR_UPDATE

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

WBEM_FLAG_UPDATE_ONLY

Esta marca hace que esta llamada se actualice. La instancia deberá existir previamente para que la llamada se realice correctamente.

WBEM_FLAG_CREATE_ONLY

Esta marca solo se usa para la creación. Si la instancia ya existe, se producirá un error en la llamada.

WBEM_FLAG_RETURN_IMMEDIATELY

Esta marca hace que sea una llamada semiincrónica. Para más información, vea Llamada a un método.

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

Normalmente , NULL, que indica que todas las propiedades de la instancia se van a actualizar. De lo contrario, se trata de un puntero a un objeto IWbemContext que contiene más información sobre la instancia. El proveedor responsable de la instancia debe documentar los datos del objeto de contexto. Un objeto IWbemContext no NULL puede indicar si existe compatibilidad con las actualizaciones parciales de instancias.

Para obtener más información sobre cómo admitir actualizaciones completas y parciales de instancias, vea IWbemServices::P utInstanceAsync. Para obtener más información sobre cómo solicitar una operación de actualización de instancia completa o parcial, consulte Modificación de una propiedad de instancia.

[out] ppCallResult

Si es NULL, no se usa este parámetro. Si el parámetro lFlags contiene WBEM_FLAG_RETURN_IMMEDIATELY, esta llamada devuelve inmediatamente con WBEM_S_NO_ERROR. A continuación, el parámetro ppCallResult recibe un puntero a un nuevo objeto IWbemCallResult , que se puede sondear con IWbemCallResult::GetCallStatus para obtener el resultado.

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.

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

Las aplicaciones y los proveedores llaman a PutInstance para crear o actualizar una instancia de una clase existente. Dependiendo de cómo se establezca el parámetro pCtx , se actualizan algunas o todas las propiedades de la instancia. Para obtener más información sobre cómo admitir la actualización parcial de instancias, vea IWbemServices::P utInstanceAsync. Para obtener más información sobre cómo solicitar una actualización parcial de una instancia, consulte Modificación de una propiedad de instancia.

El método PutInstance solo admite la creación de instancias y la actualización de instancias. No admite el movimiento de instancias. Es decir, un llamador no puede establecer el parámetro pInst en una instancia que tenga una clave que sea la misma que otra instancia de una clase del mismo nivel. Por ejemplo, supongamos que ClassA es la clase base de ClassB y ClassC. La clase ClassA define la propiedad KeyProp como su clave y ClassB tiene una instancia que tiene KeyProp establecido en 1. Para crear una instancia de ClassC con KeyProp establecido en 1, una aplicación primero debe eliminar la instancia de ClassB mediante una llamada a DeleteInstance y, a continuación, guardar la instancia de ClassC con PutInstance.

Cuando la instancia a la que apunta pInst pertenece a una subclase, Windows Management llama a todos los proveedores responsables de las clases de las que deriva la subclase. Todos estos proveedores deben realizarse correctamente para que la solicitud PutInstance original se realice correctamente. El proveedor que se corresponde con la clase superior de la jerarquía será el primero al que se llame. El orden de llamada continúa con la subclase de la clase superior y continúa de arriba a abajo hasta que Windows Management llegue al proveedor para la clase propietaria de la instancia a la que apunta pInst.

Administración de Windows no llamará a los proveedores de ninguna de las clases secundarias de una instancia. Por lo tanto, si una aplicación desea cambiar los valores de las propiedades heredadas, la aplicación debe llamar a PutInstance en la instancia completa de la clase secundaria en lugar de una instancia correspondiente de la clase primaria.

Cuando una aplicación debe actualizar una instancia que pertenece a una jerarquía de clases, el parámetro pInst debe apuntar a la instancia que contiene las propiedades que se van a modificar. Por ejemplo, suponga que tiene una instancia de destino que pertenece a la ClaseB. La instancia de la ClaseB se deriva de la ClaseA y, en la ClaseA, se define la propiedad PropA. Si una aplicación desea realizar un cambio en el valor de PropA en la instancia de ClassB , debe establecer pInst en esa instancia en lugar de una instancia de ClassA.

No se permite llamar a PutInstance en una instancia de una clase abstracta.

Requisitos

Requisito	Value
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