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

Artigo
08/27/2023

O método IWbemServices::GetObjectAsync recupera um objeto, uma definição de classe ou uma instância, com base em seu caminho. Isso é semelhante a IWbemServices::GetObject , exceto que a chamada retorna imediatamente e o objeto é fornecido ao coletor de objeto fornecido.

Atualmente, esse método recupera objetos somente do namespace associado ao ponteiro IWbemServices .

Sintaxe

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

Parâmetros

[in] strObjectPath

Caminho do objeto a ser recuperado. Para um provedor de instância, StrObjectPath pode estar no seguinte formato:

Namespace:Class.Key = "Value"
Namespace:Class = "Value"
Namespace:Class.Key = "Value", Key2 = "Value2"

Especificar o namespace antes que a classe seja opcional. Caminhos de objeto sem namespaces referem-se a instâncias no namespace atual. Se necessário, você pode substituir o caractere de aspas simples (') pelo caractere de aspas duplas (") para delimitar o início e o fim dos tipos de propriedade de cadeia de caracteres.

Se for NULL, um objeto vazio, que pode se tornar uma nova classe, será retornado. Para obter mais informações, consulte Criar uma classe.

[in] lFlags

Os sinalizadores a seguir afetam o comportamento desse método.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Se esse sinalizador for definido, o 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_DIRECT_READ

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

WBEM_FLAG_SEND_STATUS

Registra uma solicitação para receber relatórios intermediários status por meio da implementação do cliente 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.

[in] pCtx

Normalmente NULL. Caso contrário, esse é um ponteiro para um objeto IWbemContext que pode ser usado pelo provedor que produz a classe ou instância solicitada. Os valores no objeto de contexto devem ser especificados na documentação do provedor em questão. 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 objeto solicitado quando ele fica disponível por meio do método IWbemObjectSink::Indicate . O parâmetro pObjParam contém o objeto . 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 para o 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 esse parâmetro, 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.

Em caso de falha, você pode obter todas as informações disponíveis da função COM GetErrorInfoGetErrorInfo.

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

Ao implementar um provedor de instância, você deve usar o código de exemplo do analisador de caminho de objeto na seção WMI do PSDK para analisar o caminho do objeto para reconhecer qual objeto o cliente solicita. Além disso, um provedor que dá suporte a uma classe derivada só precisa fornecer os valores para as propriedades locais da classe, em vez das propriedades herdadas. O WMI solicita que o provedor da classe base manipule as propriedades herdadas.

Ao implementar um provedor de classe, GetObjectAsync deve determinar qual classe está sendo solicitada analisando o caminho do objeto de nome de classe armazenado no parâmetro strObjectPath . O método GetObjectAsync cria a classe dinamicamente ou usa a classe de um cache privado. Em seguida, GetObjectAsync envia a classe para WMI usando o ponteiro IWbemObjectSink apontado pelo parâmetro pResponseHandler . 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. 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::GetObject e Chamando um método.

Exemplos

O exemplo a seguir descreve como implementar GetObjectAsync para um provedor de instância.

SCODE CInstPro::GetObjectAsync (BSTR ObjectPath, 
                                long lFlags, IWbemContext *pCtx,
                                IWbemObjectSink FAR* pHandler)
{
    ULONG cRef;         // Reference count
    SCODE sc;
    BOOL bOK = FALSE;

    IWbemServices *  m_pNamespace;
    IWbemClassObject FAR* pObj;

    // Check arguments.

    if(ObjectPath == NULL || pHandler == NULL ||
        m_pNamespace == NULL)
        return WBEM_E_INVALID_PARAMETER;

    
    // Based on the object path, produce an empty instance
    // of the class and gather required data,
    // setting the instance's property values accordingly.
    // This example assumes that GetByPath is implemented
    // by the provider to do this.
    // The IWbemPath interface can be used to parse
    // the object path, separating the namespace and class name.

    sc = GetByPath (ObjectPath, &pObj, pCtx);
    if(sc == S_OK) 
    {
        pHandler->Indicate (1, &pObj);
        pObj->Release();
        bOK = TRUE;
    }

    sc = (bOK) ? S_OK : WBEM_E_NOT_FOUND;

    // Set status.

    pHandler->SetStatus(0,sc, NULL, NULL);

    // Free memory resources.

    SysFreeString(ObjectPath);
    m_pNamespace->Release();
    pObj->Release();

    return sc;
  
}

O exemplo a seguir mostra como um provedor de classe típico implementa GetObjectAsync.

HRESULT CStdProvider::GetObjectAsync( 
            /* [in] */ BSTR strObjectPath,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{

    IWbemClassObject *pClass = 0;

// Assume there is an IWbemServices pointer available.
// Retrieve an 'empty' object which is built up
// into the class definition.

    HRESULT hRes = m_pSvc->GetObject(NULL, 0, NULL, &pClass, 0);
    if (hRes)
        return hRes;

// Parse the object path and determine which class is   
// required. The path string is the required class name.
// Fill in the properties required for the class definition
// using pClass->Put(...), and so on.

    
    // ...

    // Send the class definition back to WMI.
    pResponseHandler->Indicate(1, &pClass);

// Indicate that it is now finished.

    pResponseHandler->SetStatus(0, WBEM_S_NO_ERROR, 0, 0);
    SysFreeString(strObjectPath);
    m_pSvc->Release();
    pClass->Release();  // This is no longer needed.
    return WBEM_S_NO_ERROR;
}

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