Metodo IWbemServices::ExecQueryAsync (wbemcli.h)

Articolo
08/27/2023

Il metodo IWbemServices::ExecQueryAsync esegue una query per recuperare gli oggetti in modo asincrono.

Sintassi

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

Parametri

[in] strQueryLanguage

BSTR valido che contiene uno dei linguaggi di query supportati da Strumentazione gestione Windows (WMI). Questo deve essere "WQL".

[in] strQuery

BSTR valido contenente il testo della query. Non può essere NULL. Quando si implementa un provider di istanze, il provider può rifiutare la query perché è troppo complessa. Quando un provider determina che una query è troppo complessa, WMI può riprovare il provider con una semplice query oppure scegliere di recuperare ed enumerare il superset delle istanze di query.

Per altre informazioni sulla compilazione di stringhe di query WMI, vedere Query con WQL e riferimento A WQL .

[in] lFlags

Questo parametro può avere uno dei valori seguenti.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Se questo flag è impostato, WMI recupera i qualificatori modificati archiviati nello spazio dei nomi localizzato delle impostazioni locali della connessione corrente. Se non è impostato, vengono recuperati solo i qualificatori archiviati nello spazio dei nomi immediato.

WBEM_FLAG_BIDIRECTIONAL

Questo flag consente a WMI di conservare i puntatori agli oggetti dell'enumerazione fino a quando il client rilascia l'enumeratore.

WBEM_FLAG_SEND_STATUS

Questo flag registra una richiesta con WMI per ricevere report sullo stato intermedio tramite l'implementazione del client di IWbemObjectSink::SetStatus. L'implementazione del provider deve supportare la creazione di report sullo stato intermedio per modificare questo flag.

WBEM_FLAG_ENSURE_LOCATABLE

Questo flag garantisce che gli oggetti restituiti dispongano di informazioni sufficienti in modo che le proprietà del sistema, ad esempio __PATH, __RELPATH e __SERVER, siano non NULL.

WBEM_FLAG_PROTOTYPE

Questo flag è utilizzato per la creazione di prototipi. Non esegue la query, ma restituisce un oggetto simile a un oggetto risultato tipico.

WBEM_FLAG_DIRECT_READ

Questo flag causa l'accesso diretto al provider per la classe specificata senza considerare la classe padre o le sottoclassi.

[in] pCtx

In genere NULL. In caso contrario, si tratta di un puntatore a un oggetto IWbemContext che il provider può usare per restituire le classi o le istanze richieste. I valori nell'oggetto contesto devono essere specificati nella documentazione del provider. Per altre informazioni su questo parametro, vedere Creazione di chiamate a WMI.

[in] pResponseHandler

Puntatore all'implementazione del chiamante di IWbemObjectSink. Questo gestore riceve gli oggetti nel set di risultati della query quando diventano disponibili. Se viene restituito un codice di errore, il puntatore IWbemObjectSink specificato non viene usato. Se viene restituito WBEM_S_NO_ERROR, viene chiamata l'implementazione IWbemObjectSink dell'utente per indicare il risultato dell'operazione. Strumentazione gestione Windows (WMI) chiama IWbemObjectSink::Indica con gli oggetti qualsiasi numero di volte, seguito da una singola chiamata a IWbemObjectSink::SetStatus per indicare lo stato finale.

WMI chiama solo AddRef al puntatore quando WBEM_S_NO_ERROR restituisce. Quando viene restituito un codice di errore, il conteggio dei riferimenti corrisponde alla voce. Per una spiegazione dettagliata dei metodi di chiamata asincroni, vedere Chiamata di un metodo.

Valore restituito

Questo metodo restituisce un HRESULT che indica lo stato della chiamata al metodo. L'elenco seguente elenca il valore contenuto in un HRESULT.

Quando si verifica un errore, è possibile ottenere informazioni dalla funzione COM GetErrorInfo.

Altri codici di errore vengono restituiti al sink dell'oggetto specificato dal parametro pResponseHandler .

I codici di errore specifici di COM potrebbero essere restituiti se i problemi di rete causano la perdita della connessione remota a WMI.

Al termine, un provider di istanze può segnalare l'esito positivo o negativo con il codice restituito da ExecQueryAsync o tramite una chiamata a SetStatus effettuata tramite pResponseHandler. Se si sceglie di chiamare SetStatus, il codice restituito inviato tramite pResponseHandler ha la precedenza.

Commenti

Esistono limiti al numero di parole chiave AND e OR che possono essere usate nelle query WQL. Un numero elevato di parole chiave WQL usate in una query complessa può causare la restituzione del codice di errore WBEM_E_QUOTA_VIOLATION come valore HRESULT . Il limite di parole chiave WQL dipende dalla complessità della query.

Il metodo IWbemObjectSink::Indicate del chiamante può essere chiamato per segnalare lo stato intermittente. Il metodo IWbemObjectSink::SetStatus viene chiamato per indicare la fine del set di risultati.

Quando un provider non supporta l'elaborazione delle query, WMI può supportarlo. Tuttavia, un'implementazione del provider di elaborazione delle query è probabilmente più efficiente rispetto alla versione WMI. Per supportare le query, il provider di istanze deve implementare il metodo ExecQueryAsync . Se un provider supporta ExecQueryAsync, WMI invia una semplice query SELECT direttamente al provider tramite il parametro strQuery e il provider deve analizzare la query e restituire le istanze pertinenti. Il provider deve analizzare la query perché WMI non modifica la query, anche quando la query viene scritta in WQL.

Per usare WMI per l'elaborazione di query, non impostare la proprietà QuerySupportLevels nella __InstanceProviderRegistration. Quando si esegue questa operazione, WMI chiama l'implementazione di CreateInstanceEnumAsync e pubblica i risultati in modo che il chiamante ottenga solo le istanze che soddisfano i criteri di query.

Nell'esempio seguente viene illustrata un'implementazione tipica del provider di istanze di ExecQueryAsync. Il metodo IWbemObjectSink::SetStatus viene chiamato per indicare la fine del set di risultati. Può anche essere chiamato senza chiamate di intervento a IWbemObjectSink::Indica se si verificano condizioni di errore.

Poiché il callback potrebbe non essere restituito allo stesso livello di autenticazione richiesto dal client, è consigliabile usare semisynchrono anziché la comunicazione asincrona. Se è necessaria la comunicazione asincrona, vedere Chiamata di un metodo.

Per altre informazioni, vedere IWbemServices::ExecQuery e Chiamata a un metodo.

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

Nell'esempio precedente il provider di istanze acquisisce un thread da WMI per eseguire le operazioni di synching necessarie. È possibile chiamare il metodo AddRef sink e creare un altro thread per recapitare gli oggetti nel set di risultati. La creazione di un altro thread consente al thread corrente di tornare a WMI senza svuotare il pool di thread. Se il provider sceglie la progettazione a thread singolo o la progettazione del doppio thread dipende dalla durata del piano del provider per l'uso del thread WMI. Non sono presenti regole fisse. La sperimentazione consente di determinare in che modo la progettazione influisce sulle prestazioni WMI.

Nota Quando i provider implementano ExecQueryAsync, sono previsti per impostazione predefinita per restituire il set di risultati corretto in base alla query. Se un provider non riesce a restituire facilmente il set di risultati corretto, può restituire un superset dei risultati e richiedere che WMI esegue post-filtro prima di recapitare gli oggetti al client per assicurarsi che il set di risultati sia corretto. A tale scopo, il provider chiama SetStatus nel sink fornito all'implementazione ExecQueryAsync , con i flag seguenti.

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

Nota Tutti gli oggetti inviati successivamente al servizio WMI vengono filtrati. Il provider può disattivare il post-filtro nel flusso intermedio usando la chiamata seguente.

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

Requisiti


Client minimo supportato	Windows Vista
Server minimo supportato	Windows Server 2008
Piattaforma di destinazione	Windows
Intestazione	wbemcli.h (include Wbemidl.h)
Libreria	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