WMI--Windows API--ExecQuery

原文来自MSDN Library for Visual Studio 2008 SP1，翻译部分仅为个人观点，想要看更多信息请看MSDN，如有版权问题请联系QQ 643166601，邮件643166601@qq.com

 

ExecQuery Method of the IWbemServices Interface
The IWbemServices::ExecQuery method executes a query to retrieve objects.
这个IWbemServices::ExecQuery方法执行一个查询取回对象。
For the valid types of queries that can be performed, see Querying with WQL.
查询有效的类型可以被执行，请看Querying with WQL。
HRESULT ExecQuery(
  [in]                 const BSTR strQueryLanguage,
  [in]                 const BSTR strQuery,
  [in]                 LONG lFlags,
  [in]                 IWbemContext* pCtx,
  [out]                IEnumWbemClassObject** ppEnum
);

Parameters
strQueryLanguage
Valid BSTR that contains one of the query languages supported by Windows Management.
有效的BSTR包含一个Windows管理支持的查询语言。
This must be "WQL", the acronym for WMI Query Language.
这必须是"WQL"，WMI Query Language的首字母缩略词。
strQuery
Valid BSTR that contains the text of the query.
有效的BSTR包含查询文本。
This parameter cannot be NULL.
这个参数不能为NULL。
lFlags
The following flags affect the behavior of this method.
以下的flags影响这个方法的行为。
The suggested value for this parameter is WBEM_FLAG_RETURN_IMMEDIATELY and WBEM_FLAG_FORWARD_ONLY for best performance.
这个最好的性能这个参数建议值是WBEM_FLAG_RETURN_IMMEDIATELY 和 WBEM_FLAG_FORWARD_ONLY。
Flag Meaning
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.
 如果设置这个flag，WMI返回修正限定符存储在命名空间中的当前连接区域设置。
 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.
 

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.

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 table 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.

Return code Description
WBEM_E_ACCESS_DENIED
 The current user does not have permission to view the result set.
 
WBEM_E_FAILED
 This indicates other unspecified errors.
 
WBEM_E_INVALID_PARAMETER
 An invalid parameter was specified.
 
WBEM_E_INVALID_QUERY
 The query was not syntactically valid.
 
WBEM_E_INVALID_QUERY_TYPE
 The requested query language is not supported.
 
WBEM_E_OUT_OF_MEMORY
 There was not enough memory to complete the operation.
 
WBEM_E_SHUTTING_DOWN
 Windows Management service was stopped and restarted.
 
 A new call to ConnectServer is required.
 
WBEM_E_TRANSPORT_FAILURE
 This indicates the failure of the remote procedure call (RPC) link between the current process and Windows Management.
 
WBEM_E_NOT_FOUND
 The query specifies a class that does not exist.
 
WBEM_S_NO_ERROR
 The call succeeded.
 

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.

Example Code
For script code examples, see WMI Tasks for Scripts and Applications and the TechNet ScriptCenter Script Repository.

For C++ code examples, see WMI C++ Application Examples.

Requirements
Client
 Requires Windows Vista, Windows XP, Windows 2000 Professional, Windows NT Workstation 4.0 SP4 and later, Windows Me, Windows 98, or Windows 95.
 
Server
 Requires Windows Server 2008, Windows Server 2003, Windows 2000 Server, or Windows NT Server 4.0 SP4 and later.
 
Header
 Declared in Wbemcli.h; include Wbemidl.h.
 
Library
 Use Wbemuuid.lib.
 
DLL
 Requires Fastprox.dll.

Requires Esscli.dll.

Requires Framedyn.dll.

Requires Ntevt.dll.

Requires Stdprov.dll.

Requires Viewprov.dll.

Requires Wbemcomn.dll.

Requires Wbemcore.dll.

Requires Wbemess.dll.

Requires Wbemsvc.dll.

Requires Wmipicmp.dll.

Requires Wmidcprv.dll.

Requires Wmipjobj.dll.

Requires Wmiprvsd.dll.
 

See Also
Querying with WQL
IWbemServices::ExecQueryAsync

 

Send comments about this topic to Microsoft

Build date: 8/15/2007