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

Artigo
08/27/2023

O método IWbemServices::CreateClassEnumAsync retorna uma enumeração de todas as classes compatíveis com o provedor de classe. O provedor de classe cria cada definição de classe do zero e retorna apenas subclasses da classe solicitada. Como um método assíncrono, CreateClassEnumAsync retorna uma mensagem status imediatamente e atualiza o coletor passado pelo parâmetro pResponseHandler, se necessário.

Quando uma chamada é bem-sucedida, o WMI chama AddRef no ponteiro pResponseHandler, retorna imediatamente e, em seguida, chama pResponseHandler de forma assíncrona– >Indique de outro thread com definições de classe até que a consulta seja atendida.

Sintaxe

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

Parâmetros

[in] strSuperclass

Se não for NULL ou em branco, esse parâmetro especificará um nome de classe pai. Somente as classes que são subclasses dessa classe são retornadas no enumerador. Se NULL ou em branco e lFlags for WBEM_FLAG_SHALLOW, somente classes de nível superior , aquelas que não têm classe pai, serão retornadas. Se for NULL ou em branco e lFlags for WBEM_FLAG_DEEP, todas as classes dentro do namespace serão retornadas.

[in] lFlags

Um ou mais dos valores a seguir são válidos.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

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

WBEM_FLAG_BIDIRECTIONAL

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

WBEM_FLAG_DEEP

Esse sinalizador força a enumeração a incluir essa e 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 uma solicitação no WMI para receber relatórios de status intermediários por meio da implementação do cliente 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.

Nota Se strSuperclass for NULL ou em branco e WBEM_FLAG_DEEP for especificado, todas as classes serão retornadas.

[in] pCtx

Normalmente NULL. Caso contrário, esse é um ponteiro para um objeto IWbemContext que pode ser usado pelo provedor que retorna as classes solicitadas. Os valores no objeto de contexto devem ser especificados na documentação do provedor. 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 os objetos conforme eles ficam disponíveis usando o método IWbemObjectSink::Indicate . Quando nenhum objeto está disponível, o método IWbemObjectSink::SetStatus é chamado pelo WMI. 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 WMI só chama AddRef no ponteiro quando WBEM_S_NO_ERROR retorna. Quando um código de erro retorna, a contagem de referência é a mesma que nenhuma entrada. Para obter uma explicação detalhada desse parâmetro, consulte Chamando um método.

Retornar valor

Esse método retorna um HRESULT que indica o status da chamada de método. Em caso de falha, você pode obter informações disponíveis da função COM GetErrorInfo. Códigos de erro específicos do COM podem ser retornados se problemas de rede fizerem com que você perca a conexão remota com o WMI. Observe que, se CreateClassEnumAsync 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. A lista a seguir lista o valor contido em um HRESULT.

Comentários

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::CreateClassEnum e Chamando um método.

Exemplos

O exemplo de código a seguir mostra como implementar CreateClassEnumAsync.

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

    // Assume there is an IWbemServices pointer available (m_pSvc).
    // Retrieve an 'empty' object that will be built up
    // into the class definition.
    
    HRESULT hRes = m_pSvc->GetObject(NULL, 0, NULL, &pClass, 0);
    if (hRes)
    {
        return hRes;
    }

    // Prepare an empty object to receive the class definition.
        IWbemClassObject *pNextClass = 0;
        hRes = pClass->Clone(&pNextClass);

    // Now loop through the private source of class definitions
    // and create each class.
    while(hRes)
    {
        // Create the class definition elsewhere.
        // For example, call a function that creates a definition:
        // FillClassDef(pNextClass);

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

        // Prepare an empty object to receive the class definition.
        IWbemClassObject *pNextClass = 0;
        hRes = pClass->Clone(&pNextClass);     
    }

    pClass->Release();

    // Send a finish message to WMI.

    pResponseHandler->SetStatus(0, hRes, 0, 0);

    return hRes;
}

No exemplo anterior, o provedor de classe 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 o design de thread único ou o design de thread duplo depende do tempo que 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


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