Provider::ExecQuery method (provider.h)
[The Provider class is part of the WMI Provider Framework which is now considered in final state, and no further development, enhancements, or updates will be available for non-security related issues affecting these libraries. The MI APIs should be used for all new development.]
The ExecQuery method is called by WMI to process a WMI Query Language (WQL) query.
HRESULT ExecQuery( MethodContext *pMethodContext, CFrameworkQuery & cQuery, long lFlags );
Pointer to the context object for this call. This value contains any IWbemContext properties specified by the client. Also, this pointer must be used as a parameter to any calls back into WMI.
Pointer to a query that has already been parsed by the provider framework.
Bitmask of flags with information about the execute query operation. This is the value specified by the client in the IWbemServices::ExecQuery method.
The following flags are handled by (and filtered out) by WMI:
The default framework provider implementation of this method returns WBEM_E_PROVIDER_NOT_CAPABLE to the calling method. The IWbemServices::ExecQuery method lists the common return values, although you can choose to return any COM return code.
WMI often calls ExecQuery in response to a client call to IWbemServices::ExecQuery, where the client passes in either a list of selected properties or a WHERE clause. WMI can also call ExecQuery if the client query contains an "ASSOCIATORS OF" or "REFERENCES OF" statement describing your class. If your implementation of ExecQuery returns WBEM_E_NOT_SUPPORTED, the client relies on WMI to handle the query.
WMI handles a query by calling your implementation of CreateInstanceEnum to provide all the instances. WMI then filters the resulting instances before returning the instances to the client. Therefore, any implementation of ExecQuery you create must be more efficient than CreateInstanceEnum.
The following describes a common implementation of ExecQuery:
- Create an empty instance of your class using Provider::CreateNewInstance.
Determine the subset of instances that you should create.
You can use methods such as IsPropertyRequired to see what properties are required, and GetValuesForProp to see what instances WMI requires. Other methods that deal with requested properties include CFrameworkQuery::GetRequiredProperties, CFrameworkQuery::AllPropertiesAreRequired, and CFrameworkQuery::KeysOnly.
- Populate the properties of the empty instance using the Set methods of the CInstance class, such as CInstance::SetByte or CInstance::SetStringArray.
- Send the instance back to the client using CInstance::Commit.
Return the appropriate return values.
The default ExecQuery framework provider implementation returns WBEM_E_PROVIDER_NOT_CAPABLE. If you implement ExecQuery, you should use the common return values listed in IWbemServices::ExecQuery. If necessary, however, you can return any COM return code.
However, you should keep the following in mind when writing your framework provider:
- Make sure you support standard queries in your association class, especially queries where the reference properties are used in a WHERE clause. For more information, see CFrameworkQuery::GetValuesForProp.
In your association class support, when you check to see if the endpoints exist, ensure you use the CWbemProviderGlue::GetInstanceKeysByPath or CWbemProviderGlue::GetInstancePropertiesByPath methods.
These methods allow the endpoints to skip populating resource-intensive or unneeded properties.
- Make sure any association endpoint classes support per-property Get methods. For more information, see Supporting Partial-Instance Operations. For more information about the query parameter, see CFrameworkQuery.
|Minimum supported client||Windows Vista|
|Minimum supported server||Windows Server 2008|
|Header||provider.h (include FwCommon.h)|