Método IWbemServices::P utInstance (wbemcli.h)

Artigo
08/27/2023

O método IWbemServices::P utInstance cria ou atualiza uma instância de uma classe existente. A instância é gravada no repositório da WMI.

Sintaxe

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

Parâmetros

[in] pInst

Ponteiro para a instância a ser gravada. O chamador não pode fazer suposições sobre a contagem de referência na conclusão dessa chamada.

[in] lFlags

Um ou mais dos valores a seguir podem ser definidos.

WBEM_FLAG_CREATE_OR_UPDATE

Esse sinalizador fará com que a instância seja criada se ela não existir ou substituída se ela já existir.

WBEM_FLAG_UPDATE_ONLY

Esse sinalizador faz com que essa chamada seja atualizada. A instância precisa existir para que a chamada seja bem-sucedida.

WBEM_FLAG_CREATE_ONLY

Esse sinalizador é usado apenas para criação. A chamada falhará se a instância já existir.

WBEM_FLAG_RETURN_IMMEDIATELY

Esse sinalizador faz com que essa seja uma chamada semissíncrona. Para obter mais informações, confira Como chamar um método.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Se esse sinalizador estiver definido, o WMI não armazenará nenhum qualificador com o sabor Alterado . Se esse sinalizador não estiver definido, supõe-se que esse objeto não esteja localizado e todos os qualificadores sejam armazenados com essa instância.

[in] pCtx

Normalmente NULL, indicando que cada propriedade na instância deve ser atualizada. Caso contrário, esse é um ponteiro para um objeto IWbemContext que contém mais informações sobre a instância. Os dados no objeto de contexto devem ser documentados pelo provedor responsável pela instância. Um objeto IWbemContext nãoNULL pode indicar se há suporte para atualizações de instância parcial.

Para obter mais informações sobre como dar suporte a atualizações completas e de instância parcial, consulte IWbemServices::P utInstanceAsync. Para obter mais informações sobre como solicitar uma operação de atualização de instância parcial ou completa, consulte Modificando uma propriedade de instância.

[out] ppCallResult

Se FOR NULL, esse parâmetro não será usado. Se o parâmetro lFlags contiver WBEM_FLAG_RETURN_IMMEDIATELY, essa chamada retornará imediatamente com WBEM_S_NO_ERROR. Em seguida, o parâmetro ppCallResult recebe um ponteiro para um novo objeto IWbemCallResult , que pode ser sondado com IWbemCallResult::GetCallStatus para obter o resultado.

Retornar valor

Esse método retorna um HRESULT que indica o status da chamada de método. A lista a seguir lista o valor contido em um HRESULT.

Códigos de erro específicos de COM também poderão ser retornados se problemas de rede fizerem com que você perca a conexão remota com o Gerenciamento do Windows.

Comentários

Aplicativos e provedores chamam PutInstance para criar ou atualizar uma instância de uma classe existente. Dependendo de como o parâmetro pCtx é definido, algumas ou todas as propriedades da instância são atualizadas. Para obter mais informações sobre como dar suporte à atualização parcial de instância, consulte IWbemServices::P utInstanceAsync. Para obter mais informações sobre como solicitar uma atualização parcial da instância, consulte Modificando uma propriedade de instância.

O método PutInstance dá suporte apenas à criação de instâncias e à atualização de instâncias. Ele não dá suporte à movimentação de instâncias. Ou seja, um chamador não pode definir o parâmetro pInst para uma instância que tenha uma chave que seja igual a outra instância em uma classe irmão. Por exemplo, suponha que ClassA seja a classe base para ClassB e ClassC. A classe ClassA define a propriedade KeyProp como sua chave e ClassB tem uma instância que tem KeyProp definido como 1. Para criar uma instância do ClassC com KeyProp definido como 1, um aplicativo deve primeiro excluir a instância de ClassB chamando DeleteInstance e, em seguida, salvar a instância de ClassC com PutInstance.

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 devem ter êxito para que a solicitação PutInstance original seja bem-sucedida. 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 atinja o 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. Portanto, se um aplicativo quiser alterar os valores das propriedades herdadas, o aplicativo deverá chamar PutInstance na instância completa da classe filho em vez de uma instância correspondente da classe pai.

Quando um aplicativo deve atualizar uma instância que pertence a uma hierarquia de classe, o parâmetro pInst deve 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 de ClassB , ele deverá definir pInst para essa instância em vez de uma instância de ClassA.

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

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 (include Wbemidl.h)
Biblioteca	Wbemuuid.lib
DLL	Fastprox.dll; Esscli.dll; FrameDyn.dll; FrameDynOS.dll; Ntevt.dll; Stdprov.dll; Viewprov.dll; Wbemcomn.dll; Wbemcore.dll; Wbemess.dll; Wbemsvc.dll; Wmipicmp.dll; Wmidcprv.dll; Wmipjobj.dll; Wmiprvsd.dll