Método IWbemServices::P utInstanceAsync (wbemcli.h)
O método IWbemServices::P utInstanceAsync cria ou atualiza de forma assíncrona uma instância de uma classe existente. O relatório de confirmação ou erro de atualização é fornecido por meio da interface IWbemObjectSink implementada pelo chamador.
Sintaxe
HRESULT PutInstanceAsync(
[in] IWbemClassObject *pInst,
[in] long lFlags,
[in] IWbemContext *pCtx,
[in] IWbemObjectSink *pResponseHandler
);
Parâmetros
[in] pInst
Ponteiro para a instância a ser gravada no repositório WMI. O chamador não pode fazer suposições sobre a contagem de referências na conclusão dessa chamada.
[in] lFlags
Especifica se o chamador deseja que a instância seja criada se a instância não existir no momento.
Ao implementar um provedor de instância, você pode optar por dar suporte a um número limitado de sinalizadores em lFlags retornando WBEM_E_PROVIDER_NOT_CAPABLE.
Essa propriedade pode ter um ou mais dos valores a seguir.
WBEM_FLAG_CREATE_OR_UPDATE
Esse sinalizador fará com que essa instância seja criada se ela não existir ou for substituída se ela já existir.
WBEM_FLAG_UPDATE_ONLY
Atualizações uma instância existente.
WBEM_FLAG_CREATE_ONLY
Esse sinalizador é apenas para criação de instância. A chamada falhará se a classe já existir.
WBEM_FLAG_SEND_STATUS
Esse sinalizador registra no Gerenciamento do Windows uma solicitação para receber relatórios de status intermediários por meio da implementação de clientes de IWbemObjectSink::SetStatus. A implementação do provedor deve dar suporte a relatórios intermediários de status para que esse sinalizador altere o comportamento.
WBEM_FLAG_USE_AMENDED_QUALIFIERS
Se esse sinalizador estiver definido, a 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
Ponteiro que descreve se o cliente está solicitando uma atualização de instância parcial ou uma atualização de instância completa. Uma atualização de instância parcial modifica um subconjunto das propriedades da instância. Por outro lado, uma atualização de instância completa modifica todas as propriedades. Se FOR NULL, esse parâmetro indicará que o aplicativo chamador está solicitando uma atualização de instância completa. Caso contrário, esse é um ponteiro para um objeto IWbemContext exigido pelo provedor de classe dinâmica que está produzindo as instâncias de classe. Para obter mais informações sobre esse parâmetro, consulte Fazendo chamadas para WMI.
[in] pResponseHandler
Ponteiro para a implementação do chamador de IWbemObjectSink. Esse manipulador recebe o status dessa chamada quando ela fica disponível usando o método IWbemObjectSink::SetStatus. Se algum código de erro for retornado, o ponteiro IWbemObjectSink fornecido não será usado. Se WBEM_S_NO_ERROR for retornado, a implementação IWbemObjectSink do usuário será chamada para indicar o resultado da operação. O Gerenciamento do Windows chama apenas AddRef no ponteiro nos casos em que WBEM_S_NO_ERROR retorna. Nos casos em que um código de erro retorna, a contagem de referência é a mesma que na entrada. Para obter mais informações sobre como fazer chamadas assíncronas, consulte Chamando um método.
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.
Observe que, se PutInstanceAsync retornar WBEM_S_NO_ERROR, o WMI aguardará um resultado do método SetStatus do manipulador de resposta. O WMI aguarda indefinidamente em uma conexão local ou até que ocorra um tempo limite de conexão remota.
Códigos de erro específicos de COM também podem ser retornados se problemas de rede fizerem com que você perca a conexão remota com o Gerenciamento do Windows.
Comentários
Os clientes que chamam PutInstanceAsync sempre devem esperar que os resultados da chamada sejam relatados usando o método IWbemObjectSink::Indicate .
Quando a instância apontada por pInst pertence a uma classe derivada de outras classes, o sucesso de PutInstanceAsync depende do sucesso dos provedores responsáveis pelas classes pai. Por exemplo, se pInst pertencer ao ClassB e ClassB derivar de ClassA, uma chamada para o método PutInstanceAsync implementada pelo provedor para ClassA deverá ter êxito para que a operação de atualização no ClassB seja bem-sucedida. Para obter mais informações, consulte Comentários em IWbemServices::P utInstance.
Ao implementar um provedor de instância, se a instância tiver uma propriedade de chave definida como NULL, PutInstanceAsync deverá escolher um valor garantido para ser exclusivo dentro da classe . Quando o WMI atende a uma solicitação para atualizar uma instância com uma propriedade de chave NULL , ela gera internamente um GUID e a atribui à propriedade key. Além disso, quando a instância que está sendo atualizada pertence a uma classe filho, o sucesso da operação depende do sucesso de uma chamada PutInstanceAsync para cada um dos provedores responsáveis pelas classes mais altas na hierarquia. Não retorne WBEM_S_NO_ERROR até ter certeza de que todos os outros provedores foram bem-sucedidos. Para obter mais informações, consulte IWbemServices::P utInstance.
Os provedores de instância que dão suporte a uma atualização parcial devem marcar para a existência do valor de contexto __PUT_EXTENSIONS. Um valor de contexto do sistema é um valor definido pelo WMI para ter significados específicos, é definido pelo aplicativo cliente e tem suporte de um provedor de instância. A interface IWbemContext fornece acesso aos valores de contexto do sistema e a outros valores de contexto específicos do provedor. A lista a seguir lista os valores de contexto que dão suporte a operações de atualização de instância parcial.
O método IWbemObjectSink::SetStatus é chamado para indicar o final do conjunto de resultados. Ele também pode ser chamado sem nenhuma chamada intervindo para IWbemObjectSink::Indique se ocorrem condições de erro.
Como o retorno de chamada pode não ser retornado no mesmo nível de autenticação exigido pelo cliente, é recomendável que você use a comunicação semissíncrona em vez de assíncrona. Se você precisar de comunicação assíncrona, consulte Chamando um método.
Para obter mais informações sobre como usar métodos de forma semissíncrona, consulte IWbemServices::P utInstance e Calling a Method.
| Valor de contexto do sistema | Descrição |
|---|---|
|
__PUT_EXTENSIONS
(VT_BOOL) |
O aplicativo cliente definiu um ou mais dos outros valores de contexto do sistema para fornecer mais informações sobre a operação de atualização. |
|
__PUT_EXT_STRICT_NULLS
(VT_BOOL) |
O provedor de instância deve forçar a configuração de propriedades a VT_NULL quando apropriado e gerar um erro em caso de falha. |
|
__PUT_EXT_PROPERTIES
(VT_ARRAY | VT_BSTR) |
Contém uma lista das propriedades a serem atualizadas. O provedor de instância deve ignorar todas as outras propriedades. |
|
__PUT_EXT_ATOMIC
(VT_BOOL) |
Todas as atualizações devem ser bem-sucedidas ou o provedor de instância deve reverter de volta. Não pode haver sucesso parcial. |
Ao implementar um provedor de instância, você deve responder a uma propriedade NULL no pCtx da seguinte maneira:
- Se o tipo de propriedade for VT_NULL, o provedor poderá ignorar a propriedade sem fazer uma alteração ou falhar na operação.
- Se o tipo de propriedade não for VT_NULL e a propriedade não puder ser atualizada, o provedor deverá retornar um erro, pois o provedor é obrigado a atualizar a propriedade com o novo valor.
Ao implementar uma operação assíncrona, a operação assíncrona não é concluída até que você libere os AddRef que você executou no pResponseHandler. Esse é o caso mesmo se você chamar SetStatus no pResponseHander. Se pResponseHandler for vazado, todos os clientes de sincronização ou semi-sincronização também não serão concluídos e possivelmente deixarão de responder, dependendo da implementação.
Mesmo em casos catastróficos, você deve liberar as referências para provedores desacoplados. Isso ocorre porque, em casos de sincronização e semi-sincronização, o serviço WMI possui a implementação de pResponseHandler: mesmo que o processo do provedor desacoplado seja encerrado, os clientes ainda não estarão respondendo.
Exemplos
O exemplo a seguir descreve como estruturar PutInstanceAsync.
HRESULT CStdProvider::PutInstanceAsync(
/* [in] */ IWbemClassObject __RPC_FAR *pInst,
/* [in] */ long lFlags,
/* [in] */ IWbemContext __RPC_FAR *pCtx,
/* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
)
{
// You must implement the InstanceIsValid method
// to check to see if the instance in the pInst variable
// is valid.
if (InstanceIsValid(lFlags, pInst))
{
return WBEM_S_NO_ERROR;
}
return WBEM_E_PROVIDER_NOT_CAPABLE;
}
Requisitos
| 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 | 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 |