IWbemServices::ExecQuery

[This is preliminary documentation and subject to change.]

The IWbemServices::ExecQuery method executes a query to retrieve objects, which are available through the returned enumerator. All query results are returned through the enumerator as IEnumWbemClassObject.

For the valid types of queries that can be performed, see Queries.

HRESULT IWbemServices::ExecQuery(
  [in] BSTR bstrQueryLanguage,             
  [in] BSTR bstrQuery,                     
  [in] LONG lFlags,                    
  [in] IWbemContext *pCtx,              
  [out] IEnumWbemClassObject **ppEnum  
);

Parameters

bstrQueryLanguage
A valid BSTR containing one of the query languages supported by CIMOM. This must be the "WQL," the acronym for WBEM Query Language.
bstrQuery
A valid BSTR containing the text of the query. This cannot be NULL.
lFlags
Reserved. It must be zero.
pCtx
Typically NULL. Otherwise, this is a pointer to an IWbemContext object required by the dynamic class provider that is producing the class instances. The values in the context object must be specified in the documentation for the provider in question.

If the query is very broad and involves many instance providers, it is not practical to include enough context information for all providers. In these cases, the parameter should be NULL.

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 zero instances. This be determined only by attempting to iterate through the instances. This object is returned with a positive reference count. The caller must call Release when the object is no longer needed.

Return Values

WBEM_E_ACCESS_DENIED The current user does not have permission to view the result set.
WBEM_E_FAILED Other unspecified errors.
WBEM_E_INVALID_PARAMETER An invalid parameter was specified, or the namespace could not be parsed.
WBEM_E_INVALID_QUERY The query was not syntactically valid.
WBEM_E_INVALID_QUERY_LANGUAGE The requested query language is not supported.
WBEM_E_OUT_OF_MEMORY There was not enough memory to complete the operation.
WBEM_E_TRANSPORT_FAILURE The communications link between the client and CIMOM has failed.
WBEM_NO_ERROR The call succeeded.

On failure, you can obtain any available information from the COM function GetErrorInfo.

See Also

Error Objects, IWbemServices::ExecQueryAsync, Queries