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

Artículo
03/08/2023

El método IWbemServices::ExecQueryAsync ejecuta una consulta para recuperar objetos de forma asincrónica.

Sintaxis

HRESULT ExecQueryAsync(
  [in] const BSTR      strQueryLanguage,
  [in] const BSTR      strQuery,
  [in] long            lFlags,
  [in] IWbemContext    *pCtx,
  [in] IWbemObjectSink *pResponseHandler
);

Parámetros

[in] strQueryLanguage

BSTR válido que contiene uno de los lenguajes de consulta que admite Instrumental de administración de Windows (WMI). Debe ser "WQL".

[in] strQuery

BSTR válido que contiene el texto de la consulta. Esto no puede ser NULL. Al implementar un proveedor de instancias, el proveedor puede rechazar la consulta porque es demasiado compleja. Cuando un proveedor determina que una consulta es demasiado compleja, WMI puede reintentar el proveedor con una consulta simple o elegir recuperar y enumerar el superconjunto de las instancias de consulta.

Para más información sobre la creación de cadenas de consulta WMI, vea Consulta con WQL y la referencia WQL.

[in] lFlags

Este parámetro puede ser uno de los valores siguientes.

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_BIDIRECTIONAL

Esta marca hace que WMI conserve punteros a objetos de la enumeración hasta que el cliente libere el enumerador.

WBEM_FLAG_SEND_STATUS

Esta marca registra una solicitud con WMI 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.

WBEM_FLAG_ENSURE_LOCATABLE

Esta marca garantiza que los objetos devueltos tengan suficiente información en ellos para que las propiedades del sistema, como __PATH, __RELPATH y __SERVER, no sean NULL.

WBEM_FLAG_PROTOTYPE

Este marcador se utiliza para los prototipos. No ejecuta la consulta, pero devuelve un objeto similar a un objeto de resultado típico.

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.

[in] pCtx

Normalmente , NULL. De lo contrario, se trata de un puntero a un objeto IWbemContext que el proveedor puede usar para devolver las clases o instancias solicitadas. Los valores del objeto de contexto deben especificarse en la documentación del proveedor. 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 los objetos del conjunto de resultados de la consulta a medida que están disponibles. 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. Instrumental de administración de Windows (WMI) llama a IWbemObjectSink::Indicar con los objetos cualquier número de veces, seguido de una sola llamada a IWbemObjectSink::SetStatus para indicar el estado final.

WMI solo llama a AddRef al puntero cuando WBEM_S_NO_ERROR devuelve. Cuando se devuelve un código de error, el recuento de referencias es el mismo que en la entrada. Para obtener una explicación detallada de los métodos de llamada asincrónicos, consulte 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.

Cuando se produce un error, puede obtener información de la función COM GetErrorInfo.

Otros códigos de error se devuelven al receptor de objetos especificado por el parámetro pResponseHandler .

Es posible que se devuelvan códigos de error específicos de COM si los problemas de red hacen que pierda la conexión remota a WMI.

Cuando haya finalizado, un proveedor de instancias puede informar de que el código devuelto es correcto o con errores de ExecQueryAsync o mediante una llamada a SetStatus realizada a través de pResponseHandler. Si decide llamar a SetStatus, el código de retorno enviado a través de pResponseHandler tiene prioridad.

Comentarios

Existe un límite en el número de palabras clave AND y OR que pueden usarse en las consultas WQL. Un gran número de palabras clave WQL usadas en una consulta compleja puede hacer que WMI devuelva el código de error WBEM_E_QUOTA_VIOLATION como valor HRESULT. El límite de palabras clave WQL que pueda usarse dependerá de la complejidad de la consulta.

Se puede llamar al método IWbemObjectSink::Indicate del autor de la llamada para notificar el estado intermitente. Se llama al método IWbemObjectSink::SetStatus para indicar el final del conjunto de resultados.

Cuando un proveedor no admite el procesamiento de consultas, WMI puede admitirlo. Sin embargo, una implementación del proveedor del procesamiento de consultas probablemente sea más eficaz que la versión de WMI. Para admitir consultas, el proveedor de instancias debe implementar el método ExecQueryAsync . Si un proveedor admite ExecQueryAsync, WMI envía unario simple consulta SELECT directamente al proveedor a través del parámetro strQuery y el proveedor debe analizar la consulta y devolver las instancias pertinentes. El proveedor debe analizar la consulta porque WMI no modifica la consulta, incluso cuando la consulta está escrita en WQL.

Para usar WMI para el procesamiento de consultas, no establezca la propiedad QuerySupportLevels en el __InstanceProviderRegistration. Al hacerlo, WMI llama a la implementación de CreateInstanceEnumAsync y publica filtra los resultados para que el autor de la llamada solo obtenga esas instancias que cumplan los criterios de consulta.

En el ejemplo siguiente se muestra una implementación típica del proveedor de instancias de ExecQueryAsync. Se llama al método IWbemObjectSink::SetStatus para indicar el final del conjunto de resultados. También se puede llamar a 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, vea IWbemServices::ExecQuery y Llamada a un método.

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

// Parse the query.
//   You must implement ParseQuery().
    if (!ParseQuery(strQuery))  return WBEM_E_PROVIDER_NOT_CAPABLE;   

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

// Call a method to determine number of instances returned.
// You need to implement the GetNumberInst function.
    int iNumInst = GetNumberInst();

// Now loop through the private source and create each   
// instance which is part of the result set of the query.
    for (int iCnt = 0 ; iCnt < iNumInst ; iCnt++)
    {
// Prepare an empty object to receive the class definition.
         IWbemClassObject *pNextInst = 0;
         hRes = pClass->SpawnInstance(0, &pNextInst);

// Create the instance.
//   You must implement FillInst().
         /*FillInst(pNextInst, iCnt);*/ 

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

// Clean up memory
    pClass->Release();
  
// Send finish message to WMI.

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

    return hRes;
}

En el ejemplo anterior, el proveedor de instancias adquiere un subproceso de WMI para realizar las operaciones de synching necesarias. Puede llamar al método AddRef receptor y crear otro subproceso para entregar los objetos en el conjunto de resultados. La creación de otro subproceso permite que el subproceso actual vuelva a WMI sin agotar el grupo de subprocesos. Si el proveedor elige el diseño de un único subproceso o el diseño de subproceso dual depende del tiempo que el proveedor planea usar el subproceso WMI. No hay reglas fijas. La experimentación puede ayudarle a determinar cómo afecta el diseño al rendimiento de WMI.

Nota Cuando los proveedores implementan ExecQueryAsync, se espera que devuelvan de forma predeterminada el conjunto de resultados correcto en función de la consulta. Si un proveedor no puede devolver fácilmente el conjunto de resultados correcto, puede devolver un superconjunto de los resultados y solicitar que WMI realice el filtrado posterior antes de entregar los objetos al cliente para asegurarse de que el conjunto de resultados sea correcto. Para ello, el proveedor llama a SetStatus en el receptor proporcionado a su implementación execQueryAsync , con las siguientes marcas.

// The pSink variable is of type IWbemObjectSink*
pSink->SetStatus(WBEM_STATUS_REQUIREMENTS,
    WBEM_REQUIREMENTS_START_POSTFILTER, 0, 0);

Nota Los objetos enviados posteriormente al servicio WMI se filtran. El proveedor puede desactivar el filtrado posterior en el flujo medio mediante la siguiente llamada.

// The pSink variable is of type IWbemObjectSink*
pSink->SetStatus(WBEM_STATUS_REQUIREMENTS, 
    WBEM_REQUIREMENTS_STOP_POSTFILTER, 0, 0);

Requisitos


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