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

Artigo
08/27/2023

O método IWbemClassObject::P ut define uma propriedade nomeada como um novo valor. Esse método sempre substitui o valor atual por um novo. Quando IWbemClassObject aponta para uma definição de classe CIM, Put cria ou atualiza o valor da propriedade. Quando IWbemClassObject aponta para uma instância cim, Put atualiza apenas um valor de propriedade. Put não pode criar um valor de propriedade.

Um usuário não pode criar propriedades com nomes que começam ou terminam com um sublinhado (_). Isso é reservado para propriedades e classes de sistema.

Sintaxe

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

Parâmetros

[in] wszName

Um parâmetro que deve apontar para um nome de propriedade válido. Esse parâmetro não pode ser NULL.

[in] lFlags

Reservado. Esse parâmetro deve ser 0 (zero).

[in] pVal

Um parâmetro que deve apontar para uma VARIANT válida, que se torna o novo valor da propriedade. Se pVal for NULL ou apontar para uma VARIANT do tipo VT_NULL, a propriedade será definida como NULL, ou seja, nenhum valor.

[in] Type

Um tipo de VARIANT apontado por pVal.

O valor NULL de uma propriedade designada por uma VARIANT do tipo VT_NULL é diferenciado de uma propriedade do tipo VT_I4 com um valor 0 (zero).

Ao criar novas propriedades, se pVal for NULL ou apontar para um VT_NULL, o tipo da propriedade será determinado do parâmetro vtType .

Se pVal deve conter um IWbemClassObject inserido, o chamador deverá chamar IWbemClassObject::QueryInterface para IID_IUnknown e colocar o ponteiro resultante na VARIANT usando um tipo de VT_UNKNOWN. O objeto original inserido é copiado durante a operação Put e, portanto, não pode ser modificado pela operação.

O ponteiro é tratado como somente leitura. O chamador deve chamar VariantClear depois que essa chamada for concluída.

Use esse parâmetro somente ao criar novas propriedades em uma definição de classe CIM e pVal é NULL ou aponta para uma VARIANT do tipo VT_NULL. Nesse caso, o parâmetro vtType especifica o tipo CIM da propriedade . Em todos os outros casos, vtType deve ser 0 (zero). Além disso, vtType deve ser 0 (zero) quando o objeto subjacente é uma instância (mesmo que pVal seja NULL), porque o tipo da propriedade é fixo e não pode ser alterado. Em outras palavras, use vtType se e somente se, pVal for NULL ou apontar para um VT_NULLVARIANT e o objeto subjacente for uma classe CIM.

Ao usar IWbemClassObject::P ut para atribuir valores de matriz vazios a uma propriedade, você não precisa especificar o tipo de VT exato; você pode atribuir um valor a pVal que é um VARIANT com um tipo variante de VT_ARRAY|VT_VARIANT.

Retornar valor

Esse método retorna um HRESULT que indica o status da chamada de método. A lista a seguir lista os valores contidos em um HRESULT. Para obter valores gerais de HRESULT , consulte Códigos de erro do sistema.

Comentários

Se a propriedade definida pelo método IWbemClassObject::P ut existir na classe pai, o valor padrão da propriedade será alterado, a menos que o tipo de propriedade não corresponda ao tipo de classe pai. Se a propriedade não existir e não for uma incompatibilidade de tipo, a propriedade será criada.

Ao executar esse método em uma instância, sempre ocorre uma substituição, pois a propriedade sempre existe.

Ao criar uma nova classe e o tipo subjacente da propriedade é uma referência de objeto, uma cadeia de caracteres de data/hora ou outro tipo especial, talvez seja necessário modificar o parâmetro de tipo CIM da propriedade para indicar a nova classe especial. O qualificador CIMType nas propriedades da instância é somente leitura e herdado do objeto de classe.

Se o tipo de variante especificado em pVal não corresponder ao tipo CIM da propriedade, o WMI tentará alterar a variante para o tipo de variante apropriado, usando as regras de coerção variante normais. Se a variante não puder ser coagida, WBEM_E_TYPE_MISMATCH será retornado. A lista a seguir lista exceções às regras normais de coerção variante quando a propriedade é tipo uint32.

Passar o tipo de variante	Result
VT_I4	S_OK
VT_I2	WBEM_TYPE_MISMATCH
VT_R8	S_OK No entanto, passar um VT_ARRAY\|VT_R8 para uma propriedade do tipo uint32[] falhará.

A propriedade do sistema __CLASS só é gravável durante a criação da classe, quando pode não ser deixada em branco. Todas as outras propriedades do sistema são somente leitura.

Exemplos

O exemplo de código a seguir mostra como definir o nome da classe para uma nova classe 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);

O exemplo de código a seguir mostra como definir o valor da propriedade SomeUint64. Lembre-se de que o valor BSTR deve estar em formato decimal e não 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	Valor
Cliente mínimo com suporte	Windows Vista
Servidor mínimo com suporte	Windows Server 2008
Plataforma de Destino	Windows
Cabeçalho	wbemcli.h (inclua Wbemidl.h)
Biblioteca	WbemUuid.lib
DLL	CIMWin32.dll; Esscli.dll; Fastprox.dll; FrameDyn.dll; FrameDynOS.dll; Krnlprov.dll; Ncprov.dll; Wbemcore.dll; Wbemess.dll; Wmipiprt.dll