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

Artículo
03/13/2024

El método IWbemServices::GetObjectAsync recupera un objeto, ya sea una definición de clase o una instancia, en función de su ruta de acceso. Esto es similar a IWbemServices::GetObject , excepto que la llamada devuelve inmediatamente y el objeto se proporciona al receptor de objetos proporcionado.

Actualmente, este método recupera objetos solo del espacio de nombres asociado al puntero IWbemServices .

Sintaxis

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

Parámetros

[in] strObjectPath

Ruta de acceso del objeto que se va a recuperar. Para un proveedor de instancias, StrObjectPath puede tener el formato siguiente:

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

Especificar el espacio de nombres antes de que la clase sea opcional. Las rutas de acceso de objeto sin espacios de nombres hacen referencia a instancias del espacio de nombres actual. Si es necesario, puede sustituir el carácter de comillas simples (') por el carácter de comillas dobles (") para delimitar los tipos de propiedades de cadena inicial y final.

Si es NULL, se devuelve un objeto vacío, que puede convertirse en una nueva clase. Para obtener más información, consulte Crear una clase.

[in] lFlags

Las marcas siguientes afectan al comportamiento de este método.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Si se establece esta marca, WMI recupera los calificadores modificados almacenados en el espacio de nombres localizado de la configuración regional de la conexión actual. Si no se establece, solo se recuperan los calificadores almacenados en el espacio de nombres inmediato.

WBEM_FLAG_DIRECT_READ

Esta marca provoca el acceso directo al proveedor de la clase especificada sin tener en cuenta su clase o subclases primarias.

WBEM_FLAG_SEND_STATUS

Registra una solicitud para recibir informes de estado intermedios a través de la implementación del cliente de IWbemObjectSink::SetStatus. La implementación del proveedor debe admitir informes de estado intermedios para que esta marca cambie el comportamiento.

[in] pCtx

Normalmente , NULL. De lo contrario, se trata de un puntero a un objeto IWbemContext que puede usar el proveedor que genera la clase o instancia solicitadas. Los valores del objeto de contexto deben especificarse en la documentación del proveedor en cuestión. Para obtener más información sobre este parámetro, vea Realizar llamadas a WMI.

[in] pResponseHandler

Puntero a la implementación del autor de la llamada de IWbemObjectSink. Este controlador recibe el objeto solicitado cuando está disponible a través del método IWbemObjectSink::Indicate . El parámetro pObjParam contiene el objeto . Si se devuelve algún código de error, no se usa el puntero IWbemObjectSink proporcionado. Si se devuelve WBEM_S_NO_ERROR , se llama a la implementación IWbemObjectSink del usuario para indicar el resultado de la operación. Administración de Windows solo llama a AddRef al puntero en los casos en los que WBEM_S_NO_ERROR devuelve. En los casos en los que se devuelve un código de error, el recuento de referencias es el mismo que en la entrada. Para obtener más información sobre este parámetro, vea Llamar a un método.

Valor devuelto

Este método devuelve un valor HRESULT que indica el estado de la llamada al método. En la lista siguiente se muestra el valor contenido en un HRESULT.

Si se produce un error, puede obtener cualquier información disponible de la función COM GetErrorInfoGetErrorInfo.

También se pueden devolver códigos de error específicos de COM si los problemas de red hacen que pierda la conexión remota a administración de Windows.

Comentarios

Al implementar un proveedor de instancias, debe usar el código de ejemplo del analizador de ruta de acceso de objeto en la sección WMI del PSDK para analizar la ruta de acceso del objeto para reconocer qué objeto solicita el cliente. Además, un proveedor que admita una clase derivada solo necesita proporcionar los valores para las propiedades locales de la clase, en lugar de las propiedades heredadas. WMI solicita que el proveedor de la clase base controle las propiedades heredadas.

Al implementar un proveedor de clases, GetObjectAsync debe determinar qué clase se solicita mediante el análisis de la ruta de acceso del objeto de nombre de clase almacenada en el parámetro strObjectPath . El método GetObjectAsync compila la clase dinámicamente o toma la clase de una caché privada. A continuación, GetObjectAsync envía la clase a WMI mediante el puntero IWbemObjectSink al que apunta el parámetro pResponseHandler . Se llama al método IWbemObjectSink::SetStatus para indicar el final del conjunto de resultados. También se puede llamar sin llamadas intermedias a IWbemObjectSink::Indicar si se producen condiciones de error.

Dado que es posible que la devolución de llamada no se devuelva en el mismo nivel de autenticación que requiere el cliente, se recomienda usar semisincrónica en lugar de comunicación asincrónica. Si necesita comunicación asincrónica, consulte Llamar a un método.

Para obtener más información sobre el uso de métodos de forma semiincrónica, vea IWbemServices::GetObject y Llamada a un método.

Ejemplos

En el ejemplo siguiente se describe cómo implementar GetObjectAsync para un proveedor de instancias.

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;
  
}

En el ejemplo siguiente se muestra cómo un proveedor de clases 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	Value
Cliente mínimo compatible	Windows Vista
Servidor mínimo compatible	Windows Server 2008
Plataforma de destino	Windows
Encabezado	wbemcli.h (include Wbemidl.h)
Library	Wbemuuid.lib
Archivo 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