Método IWbemClassObject::P ut (wbemcli.h)

Artículo
03/03/2024

El método IWbemClassObject::P ut establece una propiedad con nombre en un nuevo valor. Este método siempre sobrescribe el valor actual con uno nuevo. Cuando IWbemClassObject apunta a una definición de clase CIM, Put crea o actualiza el valor de propiedad. Cuando IWbemClassObject apunta a una instancia cim, Put solo actualiza un valor de propiedad. Put no puede crear un valor de propiedad.

Un usuario no puede crear propiedades con nombres que comiencen o terminen con un carácter de subrayado (_). Esto se reserva para las clases y las propiedades del sistema.

Sintaxis

HRESULT Put(
  [in] LPCWSTR wszName,
  [in] long    lFlags,
  [in] VARIANT *pVal,
  [in] CIMTYPE Type
);

Parámetros

[in] wszName

Parámetro que debe apuntar a un nombre de propiedad válido. Este parámetro no puede ser NULL.

[in] lFlags

Reservado. Este parámetro debe ser 0 (cero).

[in] pVal

Parámetro que debe apuntar a una VARIANT válida, que se convierte en el nuevo valor de propiedad. Si pVal es NULL o apunta a variant de tipo VT_NULL, la propiedad se establece en NULL, es decir, no hay ningún valor.

[in] Type

Un tipo de VARIANT al que apunta pVal.

El valor NULL de una propiedad designada por un variant de tipo VT_NULL se distingue de una propiedad de tipo VT_I4 con un valor 0 (cero).

Al crear nuevas propiedades, si pVal es NULL o apunta a un VT_NULL, el tipo de la propiedad se determina a partir del parámetro vtType .

Si pVal debe contener un IWbemClassObject incrustado, el autor de la llamada debe llamar a IWbemClassObject::QueryInterface para IID_IUnknown y colocar el puntero resultante en variant mediante un tipo de VT_UNKNOWN. El objeto incrustado original se copia durante la operación Put , por lo que la operación no puede modificarse.

El puntero se trata como de solo lectura. El autor de la llamada debe llamar a VariantClear una vez completada esta llamada.

Use este parámetro solo al crear nuevas propiedades en una definición de clase CIM y pVal sea NULL o apunte a un VALOR VARIANT de tipo VT_NULL. En tal caso, el parámetro vtType especifica el tipo CIM de la propiedad . En todos los demás casos, vtType debe ser 0 (cero). Además, vtType debe ser 0 (cero) cuando el objeto subyacente es una instancia (incluso si pVal es NULL), porque el tipo de la propiedad es fijo y no se puede cambiar. En otras palabras, use vtType si, y solo si, pVal es NULL o apunta a un VT_NULLVARIANT, y el objeto subyacente es una clase CIM.

Al usar IWbemClassObject::P ut para asignar valores de matriz vacíos a una propiedad, no es necesario especificar el tipo de VT exacto; puede asignar un valor a pVal que sea variant con un tipo variant de VT_ARRAY VT_VARIANT|.

Valor devuelto

Este método devuelve un valor HRESULT que indica el estado de la llamada al método. En la lista siguiente se enumeran los valores contenidos en un HRESULT. Para obtener valores HRESULT generales, consulte Códigos de error del sistema.

Comentarios

Si la propiedad establecida por el método IWbemClassObject::P ut existe en la clase primaria, el valor predeterminado de la propiedad se cambia a menos que el tipo de propiedad no coincida con el tipo de clase principal. Si la propiedad no existe y no se trata de un error de coincidencia de tipos, esta se creará.

Al ejecutar este método en una instancia de , siempre se produce una sobrescritura, porque la propiedad siempre existe.

Al crear una nueva clase y el tipo subyacente de la propiedad es una referencia de objeto, una cadena de fecha y hora u otro tipo especial, es posible que tenga que modificar el parámetro de tipo CIM para la propiedad para indicar la nueva clase especial. El calificador CIMType en las propiedades de instancia es de solo lectura y se hereda del objeto de clase.

Si el tipo de variante especificado en pVal no coincide con el tipo CIM de la propiedad, WMI intenta cambiar la variante al tipo de variante adecuado, utilizando las reglas de coerción de variante normales. Si no se puede convertir la variante, se devuelve WBEM_E_TYPE_MISMATCH . En la lista siguiente se enumeran las excepciones a las reglas de coerción de variantes normales cuando la propiedad es de tipo uint32.

Tipo de variante de paso	Resultado
VT_I4	S_OK
VT_I2	WBEM_TYPE_MISMATCH
VT_R8	S_OK Sin embargo, al pasar un VT_ARRAY\|VT_R8 a una propiedad de tipo uint32[] se producirá un error.

La propiedad del sistema __CLASS solo se puede escribir durante la creación de la clase, cuando no se puede dejar en blanco. El resto de las propiedades del sistema son de sólo lectura.

Ejemplos

En el ejemplo de código siguiente se muestra cómo establecer el nombre de clase para una nueva clase CIM.

// pObj is an empty object from IWbemServices::GetObject
// Set up the property value.
VARIANT v; 
VariantInit(&v);
V_VT(&v) = VT_BSTR;
V_BSTR(&v) = SysAllocString(L"MyClass");

// Write it.
LPCWSTR strClassProp = L"__CLASS";
pObj->Put(strClassProp, 0, &v, 0);

// Clean up.
VariantClear(&v);

En el ejemplo de código siguiente se muestra cómo establecer el valor de la propiedad SomeUint64. Tenga en cuenta que el valor BSTR debe estar en formato decimal y no hexadecimal.

// pObj is an instance containing a uint64 property
// Set up the property value.
VARIANT v; 
VariantInit(&v);
V_VT(&v) = VT_BSTR;
V_BSTR(&v) = SysAllocString(L"1033"); // - decimal format, not hex

// Write it.
LPCWSTR strClassProp = L"SomeUint64";
pObj->Put(strClassProp, 0, &v, CIM_UINT64);

// Clean up.
VariantClear(&v);

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	CIMWin32.dll; Esscli.dll; Fastprox.dll; FrameDyn.dll; FrameDynOS.dll; Krnlprov.dll; Ncprov.dll; Wbemcore.dll; Wbemess.dll; Wmipiprt.dll