Metodo Provider::ExecQuery (provider.h)

Articolo
08/25/2023

[La classe Provider fa parte di WMI Provider Framework che è ora considerata nello stato finale e non saranno disponibili ulteriori aggiornamenti, miglioramenti o aggiornamenti per problemi non correlati alla sicurezza che interessano queste librerie. Le API MI devono essere usate per tutti i nuovi sviluppi.

Il metodo ExecQuery viene chiamato da WMI per elaborare una query WQL (WMI Query Language).

Sintassi

HRESULT ExecQuery(
        MethodContext     *pMethodContext,
  [ref] CFrameworkQuery & cQuery,
        long              lFlags
);

Parametri

pMethodContext

Puntatore all'oggetto contesto per questa chiamata. Questo valore contiene le proprietà IWbemContext specificate dal client. Inoltre, questo puntatore deve essere usato come parametro per qualsiasi chiamata in WMI.

[ref] cQuery

Puntatore a una query già analizzata dal framework del provider.

lFlags

Maschera di flag con informazioni sull'operazione di esecuzione della query. Questo è il valore specificato dal client nel metodo IWbemServices::ExecQuery .

I flag seguenti vengono gestiti da (e filtrati) da WMI:

WBEM_FLAG_ENSURE_LOCATABLE
WBEM_FLAG_FORWARD_ONLY
WBEM_FLAG_BIDIRECTIONAL
WBEM_FLAG_USE_AMENDED_QUALIFIERS
WBEM_FLAG_RETURN_IMMEDIATELY
WBEM_FLAG_PROTOTYPE

Valore restituito

L'implementazione predefinita del provider di framework di questo metodo restituisce WBEM_E_PROVIDER_NOT_CAPABLE al metodo chiamante. Il metodo IWbemServices::ExecQuery elenca i valori restituiti comuni, anche se è possibile scegliere di restituire qualsiasi codice restituito COM.

Commenti

WMI spesso chiama ExecQuery in risposta a una chiamata client a IWbemServices::ExecQuery, dove il client passa in un elenco di proprietà selezionate o a una clausola WHERE. WMI può anche chiamare ExecQuery se la query client contiene un'istruzione "ASSOCIATORS OF" o "REFERENCES OF" che descrive la classe. Se l'implementazione di ExecQuery restituisce WBEM_E_NOT_SUPPORTED, il client si basa su WMI per gestire la query.

WMI gestisce una query chiamando l'implementazione di CreateInstanceEnum per fornire tutte le istanze. WMI filtra quindi le istanze risultanti prima di restituire le istanze al client. Pertanto, qualsiasi implementazione di ExecQuery creata deve essere più efficiente rispetto a CreateInstanceEnum.

Di seguito viene descritta un'implementazione comune di ExecQuery:

Creare un'istanza vuota della classe usando Provider::CreateNewInstance.
Determinare il subset di istanze che è necessario creare.
È possibile usare metodi come IsPropertyRequired per visualizzare le proprietà necessarie e GetValuesForProp per vedere quali istanze richiedono WMI. Altri metodi che gestiscono le proprietà richieste includono CFrameworkQuery::GetRequiredProperties, CFrameworkQuery::AllPropertiesAreRequired e CFrameworkQuery: :KeysOnly.
Popolare le proprietà dell'istanza vuota usando i metodi Set della classe CInstance, ad esempio CInstance::SetByte o CInstance::SetStringArray.
Inviare nuovamente l'istanza al client usando CInstance::Commit.
Restituisce i valori restituiti appropriati.
L'implementazione predefinita del provider di framework ExecQuery restituisce WBEM_E_PROVIDER_NOT_CAPABLE. Se si implementa ExecQuery, è necessario usare i valori restituiti comuni elencati in IWbemServices::ExecQuery. Se necessario, tuttavia, è possibile restituire qualsiasi codice restituito COM.

WMI non invia query "ASSOCIATORS OF" o "REFERENCES OF" tramite provider di framework. WMI usa invece lo schema per determinare quali classi sono correlate alla classe in questione e genera una query WQL appropriata per recuperare i risultati. Pertanto, non è necessario codificare alcun supporto aggiuntivo di query "ASSOCIATORS OF" e "REFERENCES OF".

Tuttavia, è consigliabile tenere presente quanto segue quando si scrive il provider di framework:

Assicurarsi di supportare le query standard nella classe di associazione, in particolare le query in cui vengono usate le proprietà di riferimento in una clausola WHERE. Per altre informazioni, vedere CFrameworkQuery::GetValuesForProp.
Nel supporto della classe di associazione, quando si verifica se esistono gli endpoint, assicurarsi di usare i metodi CWbemProviderGlue::GetInstanceKeysByPath o CWbemProviderGlue ::GetInstancePropertiesByPath.
Questi metodi consentono agli endpoint di ignorare la popolamento delle proprietà a elevato utilizzo di risorse o non consentite.
Assicurarsi che tutte le classi dell'endpoint di associazione supportino i metodi Get per proprietà. Per altre informazioni, vedere Supporto delle operazioni di Partial-Instance. Per altre informazioni sul parametro di query, vedere CFrameworkQuery.

Requisiti


Client minimo supportato	Windows Vista
Server minimo supportato	Windows Server 2008
Piattaforma di destinazione	Windows
Intestazione	provider.h (includere FwCommon.h)
Libreria	FrameDyn.lib
DLL	FrameDynOS.dll; FrameDyn.dll