Compartilhar via

Função PutInstanceWmi

  • Artigo

Cria ou atualiza uma instância de uma classe existente. A instância é gravada no repositório da WMI.

Observação

Esta API é somente para uso interno. Ela não é destinada ao uso do código do desenvolvedor.

Sintaxe

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

Parâmetros

pInst
[in] Um ponteiro para a instância a ser gravada.

lFlags
[in] Uma combinação de sinalizadores que afetam o comportamento dessa função. Os seguintes valores são definidos no arquivo de cabeçalho WbemCli.h ou você pode defini-los como constantes em seu código:

Constante Valor Descrição
WBEM_FLAG_USE_AMENDED_QUALIFIERS 0x20000 Se definido, o WMI não armazenará nenhum qualificador com o sabor alterado .
Se não estiver definido, supõe-se que esse objeto não está localizado e todos os qualificadores estão armazenados com essa instância.
WBEM_FLAG_CREATE_OR_UPDATE 0 Crie a instância se ela não existir ou substitua-a se já existir.
WBEM_FLAG_UPDATE_ONLY 1 Atualize a instância. A instância precisa existir para que a chamada seja bem-sucedida.
WBEM_FLAG_CREATE_ONLY 2 Crie a instância. A chamada falhará se a instância já existir.
WBEM_FLAG_RETURN_IMMEDIATELY 0x10 O sinalizador causa uma chamada de método semissíncrono.

pCtx
[in] Normalmente, esse valor é null. Caso contrário, ele é um ponteiro para uma instância IWbemContext que pode ser usada pelo provedor que está fornecendo as classes solicitadas.

ppCallResult
[out] Se null, esse parâmetro não está em uso. Se lFlags contiver WBEM_FLAG_RETURN_IMMEDIATELY, a função retornará imediatamente com WBEM_S_NO_ERROR. O parâmetro ppCallResult recebe um ponteiro para um novo objeto IWbemCallResult .

Valor retornado

Os seguintes valores retornados por essa função são definidos no arquivo de cabeçalho WbemCli.h, ou você pode defini-los como constantes em seu código:

Constante Valor Descrição
WBEM_E_ACCESS_DENIED 0x80041003 O usuário não tem permissão para atualizar uma instância da classe especificada.
WBEM_E_FAILED 0x80041001 Ocorreu um erro não especificado.
WBEM_E_INVALID_CLASS 0x80041010 A classe que permite essa instância não é válida.
WBEM_E_ILLEGAL_NULL 0x80041028 Um null foi especificado para uma propriedade que não pode ser null, como uma que é marcada por um qualificador indexado ou não nulo.
WBEM_E_INVALID_OBJECT 0x8004100f A instância especificada é inválida. (Por exemplo, chamar PutInstanceWmi com uma classe retorna esse valor.)
WBEM_E_INVALID_PARAMETER 0x80041008 Um parâmetro não é válido.
WBEM_E_ALREADY_EXISTS 0x80041019 O sinalizador WBEM_FLAG_CREATE_ONLY foi especificado, mas a instância já existe.
WBEM_E_NOT_FOUND 0x80041002 WBEM_FLAG_UPDATE_ONLY foi especificado em lFlags, mas a instância não existe.
WBEM_E_OUT_OF_MEMORY 0x80041006 Não há memória disponível suficiente para concluir a operação.
WBEM_E_SHUTTING_DOWN 0x80041033 O WMI provavelmente foi interrompido e reiniciado. Chame ConnectServerWmi novamente.
WBEM_E_TRANSPORT_FAILURE 0x80041015 Falha no link da RPC (chamada de procedimento remoto) entre o processo atual e o WMI.
WBEM_S_NO_ERROR 0 A chamada de função foi bem-sucedida.

Comentários

Essa função faz o encapsulamento de uma chamada para o método IWbemServices::PutInstance.

A função PutInstanceWmi permite apenas criar instâncias e atualizar instâncias de classes existentes. Dependendo de como o parâmetro pCtx é definido, algumas ou todas as propriedades da instância são atualizadas.

Quando a instância apontada por pInst pertence a uma subclasse, o Gerenciamento do Windows chama todos os provedores responsáveis pelas classes das quais a subclasse deriva. Todos esses provedores precisam ter êxito para que a solicitação original PutInstanceWmi tenha êxito. O provedor que permite classe mais alta na hierarquia é chamado primeiro. A ordem de chamada continua com a subclasse da classe mais alta e prossegue de cima para baixo até que o Gerenciamento do Windows chegue ao provedor para a classe que possui a instância apontada por pInst. O Gerenciamento do Windows não chama os provedores para nenhuma das classes filho de uma instância.

Quando um aplicativo precisa atualizar uma instância que pertence a uma hierarquia de classe, o parâmetro pInst precisa apontar para a instância que contém as propriedades a serem modificadas. Ou seja, considere uma instância de destino que pertence a ClassB. A instância ClassB deriva de ClassA e ClassA define a propriedade PropA. Se um aplicativo quiser fazer uma alteração no valor de PropA na instância ClassB, ele precisará definir pInst para essa instância em vez de uma instância ClassA.

Não é permitido chamar PutInstanceWmi em uma instância de classe abstrata.

Se a chamada de função falhar, você poderá obter informações de erro adicionais se chamar a função GetErrorInfo.

Requisitos

Plataformas: confira Requisitos do sistema.

Header: WMINet_Utils.idl

Versões do .NET Framework: Disponível desde 4.7.2

Confira também