IWbemServices::ExecQuery method (wbemcli.h)
The IWbemServices::ExecQuery method executes a query to retrieve objects.
For the valid types of queries that can be performed, see Querying with WQL.
Syntax
HRESULT ExecQuery(
[in] const BSTR strQueryLanguage,
[in] const BSTR strQuery,
[in] long lFlags,
[in] IWbemContext *pCtx,
[out] IEnumWbemClassObject **ppEnum
);
Parameters
[in] strQueryLanguage
Valid BSTR that contains one of the query languages supported by Windows Management. This must be "WQL", the acronym for WMI Query Language.
[in] strQuery
Valid BSTR that contains the text of the query. This parameter cannot be NULL. For more information on building WMI query strings, see Querying with WQL and the WQL reference.
[in] lFlags
The following flags affect the behavior of this method. The suggested value for this parameter is WBEM_FLAG_RETURN_IMMEDIATELY and WBEM_FLAG_FORWARD_ONLY for best performance.
WBEM_FLAG_USE_AMENDED_QUALIFIERS
If this flag is set, WMI retrieves the amended qualifiers stored in the localized namespace of the current connection's locale. If not set, only the qualifiers stored in the immediate namespace are retrieved.
WBEM_FLAG_FORWARD_ONLY
This flag causes a forward-only enumerator to be returned. Forward-only enumerators are generally much faster and use less memory than conventional enumerators but do not allow calls to Clone or Reset.
WBEM_FLAG_BIDIRECTIONAL
This flag causes Windows Management to retain pointers to objects of the enumeration until the client releases the enumerator.
WBEM_FLAG_RETURN_IMMEDIATELY
This flag causes this to be a semisynchronous call. For more information, see Calling a Method.
WBEM_FLAG_ENSURE_LOCATABLE
This flag ensures that any returned objects have enough information in them so that the system properties, such as __PATH, __RELPATH, and __SERVER, are non-NULL.
WBEM_FLAG_PROTOTYPE
This flag is used for prototyping. It does not execute the query and instead returns an object that looks like a typical result object.
WBEM_FLAG_DIRECT_READ
This flag causes direct access to the provider for the class specified without any regard to its parent class or subclasses.
[in] pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object that can be used by the provider that is providing the requested classes or instances. The values in the context object must be specified in the documentation for the provider in question. For more information about this parameter, see Making Calls to WMI.
[out] ppEnum
If no error occurs, this receives the enumerator that allows the caller to retrieve the instances in the result set of the query. It is not an error for the query to have a result set with 0 instances. This is determined only by attempting to iterate through the instances. This object returns with a positive reference count. The caller must call Release when the object is no longer required.
Return value
This method returns an HRESULT that indicates the status of the method call. The following list lists the value contained within an HRESULT.
On failure, you can obtain any available information from the COM function GetErrorInfo.
COM-specific error codes also can be returned if network problems cause you to lose the remote connection to Windows Management.
Remarks
The IWbemServices::ExecQuery method processes the query specified in the strQuery parameter and creates an enumerator through which the caller can access the query results. The enumerator is a pointer to an IEnumWbemClassObject interface; the query results are instances of class objects made available through the IWbemClassObject interface.
There are limits to the number of "AND" and "OR" keywords that can be used in WQL queries. Large numbers of WQL keywords used in a complex query can cause WMI to return the WBEM_E_QUOTA_VIOLATION error code as an HRESULT value. The limit of WQL keywords depends on how complex the query is.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista |
| Minimum supported server | Windows Server 2008 |
| Target Platform | Windows |
| Header | wbemcli.h (include Wbemidl.h) |
| Library | 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 |