Partilhar via

Função PutInstanceWmi

  • Artigo

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

Nota

Esta API destina-se apenas a utilização interna. Não se destina a ser utilizado a partir do código do programador.

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 escrever.

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

Constante Valor Descrição
WBEM_FLAG_USE_AMENDED_QUALIFIERS 0x20000 Se estiver definido, a WMI não armazena nenhum qualificador com o sabor Alterado .
Se não estiver definido, presume-se que este objeto não está localizado e todos os qualificadores são armazenados com esta instância.
WBEM_FLAG_CREATE_OR_UPDATE 0 Crie a instância se não existir ou substitua-a se já existir.
WBEM_FLAG_UPDATE_ONLY 1 Atualize a instância. A instância tem de existir para que a chamada seja bem-sucedida.
WBEM_FLAG_CREATE_ONLY 2 Crie a instância. A chamada falha se a instância já existir.
WBEM_FLAG_RETURN_IMMEDIATELY 0x10 O sinalizador causa uma chamada semissíncrona.

pCtx
[in] Normalmente, este valor é null. Caso contrário, é um ponteiro para uma instância IWbemContext que pode ser utilizada pelo fornecedor que está a fornecer as classes pedidas.

ppCallResult
[fora] Se null, este parâmetro não é utilizado. Se lFlags contiver WBEM_FLAG_RETURN_IMMEDIATELY, a função devolve imediatamente com WBEM_S_NO_ERROR. O ppCallResult parâmetro recebe um ponteiro para um novo objeto IWbemCallResult .

Valor devolvido

Os seguintes valores devolvidos por esta função são definidos no ficheiro de cabeçalho WbemCli.h ou pode defini-los como constantes no seu código:

Constante Valor Descrição
WBEM_E_ACCESS_DENIED 0x80041003 O utilizador 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 suporta esta instância não é válida.
WBEM_E_ILLEGAL_NULL 0x80041028 null foi especificado para uma propriedade que não pode ser null, como uma que está marcada por um qualificador Indexado ou Not_Null.
WBEM_E_INVALID_OBJECT 0x8004100f A instância especificada não é válida. (Por exemplo, chamar PutInstanceWmi com uma classe devolve este valor.)
WBEM_E_INVALID_PARAMETER 0x80041008 Um parâmetro não é válido.
WBEM_E_ALREADY_EXISTS 0x80041019 O WBEM_FLAG_CREATE_ONLY sinalizador 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 existe memória suficiente disponível para concluir a operação.
WBEM_E_SHUTTING_DOWN 0x80041033 O WMI foi provavelmente parado e reiniciado. Ligue novamente para ConnectServerWmi .
WBEM_E_TRANSPORT_FAILURE 0x80041015 A ligação de chamada de procedimento remoto (RPC) entre o processo atual e a WMI falhou.
WBEM_S_NO_ERROR 0 A chamada da função foi efetuada com êxito.

Observações

Esta função encapsula uma chamada para o método IWbemServices::P utInstance .

A PutInstanceWmi função suporta a criação de instâncias e a atualização de instâncias apenas de classes existentes. Consoante a forma como o pCtx parâmetro é definido, algumas ou todas as propriedades da instância são atualizadas.

Quando a instância apontada por pInst pertence a uma subclasse, a Gestão do Windows chama todos os fornecedores responsáveis pelas classes a partir das quais a subclasse deriva. Todos estes fornecedores têm de ter êxito para que o pedido original PutInstanceWmi seja bem-sucedido. O fornecedor que suporta a classe mais alta da hierarquia é chamado primeiro. A ordem de chamadas continua com a subclasse da classe mais alta e avança de cima para baixo até que a Gestão do Windows chegue ao fornecedor da classe proprietária da instância apontada por pInst. A Gestão do Windows não chama os fornecedores de nenhuma das classes subordinadas de uma instância.

Quando uma aplicação tem de atualizar uma instância que pertence a uma hierarquia de classes, o pInst parâmetro tem de apontar para a instância que contém as propriedades a modificar. Ou seja, considere uma instância de destino que pertence à ClasseB. A instância classb deriva da ClasseA e ClassA define a propriedade PropA. Se uma aplicação quiser fazer uma alteração ao valor de PropA na instância da ClasseB , tem de ser definida pInst para essa instância em vez de uma instância de ClassA.

Não é permitida a chamada PutInstanceWmi numa instância de uma classe abstrata.

Se a chamada da função falhar, pode obter informações de erro adicionais ao chamar a função GetErrorInfo .

Requisitos

Plataformas: Veja Requisitos de Sistema.

Cabeçalho: WMINet_Utils.idl

.NET Framework Versões: Disponível desde a versão 4.7.2

Ver também