Método IWbemServices::CreateInstanceEnumAsync (wbemcli.h)

O método IWbemServices::CreateInstanceEnumAsync cria um enumerador que retorna de forma assíncrona as instâncias de uma classe especificada de acordo com os critérios de seleção especificados pelo usuário. Esse método dá suporte a consultas WQL (Linguagem de Consulta WMI) simples. Consultas mais complexas podem ser processadas usando o método IWbemServices::ExecQueryAsync .

Sintaxe

HRESULT CreateInstanceEnumAsync(
  [in] const BSTR      strFilter,
  [in] long            lFlags,
  [in] IWbemContext    *pCtx,
  [in] IWbemObjectSink *pResponseHandler
);

Parâmetros

[in] strFilter

BSTR válido que contém o nome da classe para a qual as instâncias são desejadas. Esse parâmetro não pode ser NULL.

[in] lFlags

Esse parâmetro pode usar um dos valores a seguir.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Se esse sinalizador for definido, a Instrumentação de Gerenciamento do Windows (WMI) recuperará os qualificadores alterados armazenados no namespace localizado da localidade da conexão atual. Se não estiver definido, somente os qualificadores armazenados no namespace imediato serão recuperados.

WBEM_FLAG_DEEP

Esse sinalizador força a enumeração a incluir instâncias desse e de todas as subclasses na hierarquia.

WBEM_FLAG_SHALLOW

Esse sinalizador força a enumeração a incluir apenas instâncias puras dessa classe, excluindo todas as instâncias de subclasses, que fornecem propriedades não encontradas nessa classe.

WBEM_FLAG_SEND_STATUS

Esse sinalizador registra no Gerenciamento do Windows uma solicitação para receber relatórios intermediários status por meio da implementação de clientes de IWbemObjectSink::SetStatus. A implementação do provedor deve dar suporte a relatórios de status intermediários para que esse sinalizador altere o comportamento.

WBEM_FLAG_BIDIRECTIONAL

Esse sinalizador faz com que o Gerenciamento do Windows mantenha ponteiros para objetos da enumeração até que o cliente libere o enumerador.

WBEM_FLAG_DIRECT_READ

Esse sinalizador causa acesso direto ao provedor para a classe especificada sem qualquer relação com sua classe pai ou subclasses.

[in] pCtx

Normalmente NULL. Caso contrário, esse é um ponteiro para um objeto IWbemContext que pode ser usado pelo provedor que está retornando as instâncias solicitadas. Os valores no objeto de contexto devem ser especificados na documentação do provedor em questão. Para obter mais informações, consulte Fazer chamadas para o WMI.

[in] pResponseHandler

Ponteiro para a implementação do chamador de IWbemObjectSink. Esse manipulador recebe os objetos conforme eles ficam disponíveis. 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 Somente 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, confira Como chamar 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.

Em caso de falha, você pode obter mais informações da função COM GetErrorInfo.

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.

Um provedor de instância pode relatar êxito ou falha com o código de retorno de CreateInstanceEnumAsync ou por meio de uma chamada para SetStatus feita por meio de pResponseHandler. Se você optar por chamar SetStatus, o código de retorno enviado por meio de pResponseHandler terá precedência.

Se CreateInstanceEnumAsync 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.

Comentários

O método IWbemObjectSink::SetStatus é chamado para indicar o final do conjunto de resultados. Ele também pode ser chamado sem chamadas intermediárias para IWbemObjectSink::Indicar 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.

Para obter mais informações, consulte IWbemServices::CreateInstanceEnum e Chamando um método.

Exemplos

O exemplo a seguir mostra como implementar CreateInstanceEnumAsync.

#define NUM_OF_INSTANCES 3

HRESULT CStdProvider::CreateInstanceEnumAsync( 
            /* [in] */ BSTR strClass,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
    IWbemClassObject *pClass = 0; 
    IWbemClassObject *pNextInst = 0;

    // Assume there is an IWbemServices pointer available to
    // retrieve the class definition.
    HRESULT hRes = m_pSvc->GetObject(strClass, 0, NULL, &pClass, 0);
    if (hRes)
        return hRes;

    // Now loop through the private source and create each instance.
    for (int i = 0; i < NUM_OF_INSTANCES; i++)
    {
         // Prepare an empty object to receive the class definition.
         pClass->SpawnInstance(0, &pNextInst);

         // Create the instance.
         // For example, create the instance in a
         // FillInst method you implement:
         /*FillInst(pNextInst);*/

         // Deliver the class to WMI.
         pResponseHandler->Indicate(1, &pNextInst);
         pNextInst->Release();
    }

    // Send a finish message to WMI.
    pResponseHandler->SetStatus(0, WBEM_S_NO_ERROR, 0, 0);

    // Free memory resources.
    SysFreeString(strClass);
    pClass->Release();
    m_pSvc->Release();

    return WBEM_S_NO_ERROR;
}

No exemplo anterior, o provedor de instância adquire um thread do WMI para executar as operações necessárias. Talvez você queira chamar o método AddRef do coletor e criar outro thread para entregar os objetos no conjunto de resultados. A criação de outro thread permite que o thread atual retorne ao WMI sem esgotar o pool de threads. Se o provedor escolhe ou não o design de thread único em vez do design de thread duplo depende de quanto tempo o provedor planeja usar o thread WMI. Não há regras fixas. A experimentação pode ajudá-lo a determinar como seu design afeta o desempenho do WMI.

Requisitos

Confira também

Como chamar um método

IWbemServices

IWbemServices::CreateInstanceEnum