Compartir a través de

Función PutInstanceWmi

  • Artículo

Crea o actualiza una instancia de una clase existente. La instancia se escribe en el repositorio de la WMI.

Nota

Esta API es solo para uso interno. No está pensada para usarla desde código del desarrollador.

Sintaxis

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

Parámetros

pInst
[in] El valor de este parámetro se corresponde con un puntero que apunta a la instancia que se va a escribir.

lFlags
[in] El valor de este parámetro se corresponde con una combinación de marcas que afectan al comportamiento de esta función. Los siguientes valores se definen en el archivo de encabezado WbemCli.h, aunque también puede definirlos como constantes en el código. Puede consultarlos a continuación:

Constante Value Descripción
WBEM_FLAG_USE_AMENDED_QUALIFIERS 0x20000 Si se establece este valor, WMI no almacenará ningún calificador que tenga el tipo Modificado.
Si no se establece, se supondrá que este objeto no está localizado y todos los calificadores se almacenarán con esta instancia.
WBEM_FLAG_CREATE_OR_UPDATE 0 Si se establece este valor, se creará la instancia si no existe o se sobrescribirá si ya existe.
WBEM_FLAG_UPDATE_ONLY 1 Si se establece este valor, se actualizará la instancia. La instancia deberá existir previamente para que la llamada se realice correctamente.
WBEM_FLAG_CREATE_ONLY 2 Cree la instancia. Si la instancia ya existe, se producirá un error en la llamada.
WBEM_FLAG_RETURN_IMMEDIATELY 0x10 Si se establece esta marca, se producirá una llamada semisincrónica.

pCtx
[in] Normalmente, este valor es null. De lo contrario, es un puntero que apunta a una instancia de la interfaz IWbemContext que puede usarse en el proveedor que proporciona las clases que se solicitan.

ppCallResult
[out] Si el valor es null, este parámetro no se usa. Si el parámetro lFlags contiene la marca WBEM_FLAG_RETURN_IMMEDIATELY, la función se devolverá inmediatamente con el valor WBEM_S_NO_ERROR. El parámetro ppCallResult se usa para obtener un puntero que apunta a un nuevo objeto IWbemCallResult.

Valor devuelto

Los siguientes valores que devuelve esta función se definen en el archivo de encabezado WbemCli.h, aunque también puede definirlos como constantes en el código. Puede consultarlos a continuación:

Constante Value Descripción
WBEM_E_ACCESS_DENIED 0x80041003 Si se devuelve este valor, significa que el usuario no tiene permiso para actualizar una instancia de la clase que se especifica.
WBEM_E_FAILED 0x80041001 Error no especificado.
WBEM_E_INVALID_CLASS 0x80041010 Si se devuelve este valor, significa que la clase que admite esta instancia no es válida.
WBEM_E_ILLEGAL_NULL 0x80041028 Si se devuelve este valor, significa que se especificó un valor null en una propiedad que no puede tener el valor null, como las que están marcada con un calificador Indexed o Not_Null.
WBEM_E_INVALID_OBJECT 0x8004100f La instancia especificada no es válida. (Por ejemplo, este valor se devuelve al llamar a la función PutInstanceWmi mediante una clase).
WBEM_E_INVALID_PARAMETER 0x80041008 Un parámetro no es válido.
WBEM_E_ALREADY_EXISTS 0x80041019 Si se devuelve este valor, significa que se especificó la marca WBEM_FLAG_CREATE_ONLY pero la instancia ya existía.
WBEM_E_NOT_FOUND 0x80041002 Si se devuelve este valor, significa que se especificó la marca WBEM_FLAG_UPDATE_ONLY en el parámetro lFlags, pero la instancia no existe.
WBEM_E_OUT_OF_MEMORY 0x80041006 Memoria insuficiente para completar la operación.
WBEM_E_SHUTTING_DOWN 0x80041033 Si se devuelve este valor, significa que es probable que WMI se encontrara en un proceso de detención y reinicio. En este caso, vuelva a llamar a la función ConnectServerWmi.
WBEM_E_TRANSPORT_FAILURE 0x80041015 Si se devuelve este valor, significará que ha ocurrido un error en el vínculo de llamada a procedimiento remoto (RPC) entre el proceso actual y WMI.
WBEM_S_NO_ERROR 0 Si se devuelve este valor, significará que la llamada a la función se realizó correctamente.

Comentarios

Al usar esta función, se ajusta una llamada al método IWbemServices::PutInstance.

El uso de la función PutInstanceWmi solo se admite para la creación y la actualización de instancias de clases existentes. Dependiendo de cómo se establezca el parámetro pCtx, se actualizarán algunas o todas las propiedades de la instancia.

Si la instancia a la que se apunta desde el parámetro pInst pertenece a una subclase, Administración de Windows llamará a todos los proveedores responsables de las clases desde las que se deriva esa subclase. Todas las llamadas a estos proveedores deberán realizarse correctamente para que la solicitud original a la función PutInstanceWmi 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 continuará con la subclase de la clase superior y, después continuará de arriba a abajo hasta que Administración de Windows llegue al proveedor de la clase propietaria de la instancia a la que se apunta desde el parámetro pInst. Administración de Windows no llamará a los proveedores de ninguna de las clases secundarias de una instancia.

Si una aplicación debe actualizar una instancia que pertenece a una jerarquía de clases, el parámetro pInst deberá establecerse de forma que apunte a la instancia donde se incluyan las propiedades que se vayan 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 debe realizar un cambio en el valor de PropA de la instancia de la ClaseB, el valor del parámetro pInst deberá establecerse en esa instancia en lugar de en una instancia de la ClaseA.

No se permite llamar a la función PutInstanceWmi en una instancia de una clase abstracta.

Si se produce un error en la llamada a la función, podrá obtener información adicional sobre este mediante una llamada a la función GetErrorInfo.

Requisitos

Plataformas: Vea Requisitos de sistema.

Encabezado: WMINet_Utils.idl

Versiones de .NET Framework: está disponible desde la versión 4.7.2

Consulte también