IWbemServices：：CreateInstanceEnumAsync 方法 (wbemcli.h)

项目
08/27/2023

IWbemServices：：CreateInstanceEnumAsync 方法创建一个枚举器，该枚举器根据用户指定的选择条件异步返回指定类的实例。此方法支持简单的 WMI 查询语言 (WQL) 查询。可以使用 IWbemServices：：ExecQueryAsync 方法处理更复杂的查询。

语法

HRESULT CreateInstanceEnumAsync(
  [in] const BSTR      strFilter,
  [in] long            lFlags,
  [in] IWbemContext    *pCtx,
  [in] IWbemObjectSink *pResponseHandler
);

参数

[in] strFilter

包含需要实例的类名称的有效 BSTR 。此参数不能为 NULL。

[in] lFlags

此参数的取值可为下列值之一：

WBEM_FLAG_USE_AMENDED_QUALIFIERS

如果设置了此标志，Windows Management Instrumentation (WMI) 将检索当前连接区域设置的本地化命名空间中存储的修改后的限定符。如果未设置，则仅检索存储在直接命名空间中的限定符。

WBEM_FLAG_DEEP

此标志强制枚举包含此子类的实例以及层次结构中的所有子类。

WBEM_FLAG_SHALLOW

此标志强制枚举仅包含此类的纯实例，不包括子类的所有实例，这些实例提供此类中找不到的属性。

WBEM_FLAG_SEND_STATUS

此标志向 Windows 管理注册请求，以通过客户端实现的 IWbemObjectSink：：SetStatus 接收中间状态报告。提供程序实现必须支持此标志的中间状态报告才能更改行为。

WBEM_FLAG_BIDIRECTIONAL

此标志会导致 Windows 管理保留指向枚举对象的指针，直到客户端释放枚举器。

WBEM_FLAG_DIRECT_READ

此标志导致直接访问指定的类的提供程序，而不考虑其父类或子类。

[in] pCtx

通常为 NULL。否则，这是指向 IWbemContext 对象的指针，该对象可由返回所请求实例的提供程序使用。上下文对象中的值必须在相关提供程序的文档中指定。有关详细信息，请参阅调用 WMI。

[in] pResponseHandler

指向调用方实现 IWbemObjectSink 的指针。此处理程序在对象变为可用时接收这些对象。如果返回任何错误代码，则不使用提供的 IWbemObjectSink 指针。如果返回 WBEM_S_NO_ERROR ，则将调用用户的 IWbemObjectSink 实现来指示操作的结果。 Windows 管理仅在返回WBEM_S_NO_ERROR的情况下对指针调用 AddRef。在错误代码返回的情况下，引用计数与输入时相同。有关详细信息，请参阅调用方法。

返回值

此方法返回指示方法调用状态的 HRESULT。以下列表列出了 HRESULT 中包含的值。

失败时，可以从 COM 函数 GetErrorInfo 获取详细信息。

如果网络问题导致你失去与 Windows 管理的远程连接，也可能会返回特定于 COM 的错误代码。

实例提供程序可以使用 CreateInstanceEnumAsync 中的返回代码或通过 pResponseHandler 调用 SetStatus 来报告成功或失败。如果选择调用 SetStatus，则通过 pResponseHandler 发送的返回代码优先。

如果 CreateInstanceEnumAsync 返回 WBEM_S_NO_ERROR，则 WMI 将等待响应处理程序的 SetStatus 方法的结果。 WMI 将无限期等待本地连接，或直到远程连接超时。

注解

调用 IWbemObjectSink：：SetStatus 方法以指示结果集的结束。还可以调用它，而无需干预调用 IWbemObjectSink：：指示是否发生错误条件。

由于回调可能不会在客户端所需的相同身份验证级别返回，因此建议使用半同步通信而不是异步通信。

有关详细信息，请参阅 IWbemServices：：CreateInstanceEnum 和调用方法。

示例

以下示例演示如何实现 CreateInstanceEnumAsync。

#define NUM_OF_INSTANCES 3

HRESULT CStdProvider::CreateInstanceEnumAsync( 
            /* [in] */ BSTR strClass,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
    IWbemClassObject *pClass = 0; 
    IWbemClassObject *pNextInst = 0;

    // Assume there is an IWbemServices pointer available to
    // retrieve the class definition.
    HRESULT hRes = m_pSvc->GetObject(strClass, 0, NULL, &pClass, 0);
    if (hRes)
        return hRes;

    // Now loop through the private source and create each instance.
    for (int i = 0; i < NUM_OF_INSTANCES; i++)
    {
         // Prepare an empty object to receive the class definition.
         pClass->SpawnInstance(0, &pNextInst);

         // Create the instance.
         // For example, create the instance in a
         // FillInst method you implement:
         /*FillInst(pNextInst);*/

         // Deliver the class to WMI.
         pResponseHandler->Indicate(1, &pNextInst);
         pNextInst->Release();
    }

    // Send a finish message to WMI.
    pResponseHandler->SetStatus(0, WBEM_S_NO_ERROR, 0, 0);

    // Free memory resources.
    SysFreeString(strClass);
    pClass->Release();
    m_pSvc->Release();

    return WBEM_S_NO_ERROR;
}

在前面的示例中，实例提供程序从 WMI 获取线程以执行任何必要的操作。你可能想要调用接收器 AddRef 方法并创建另一个线程来传送结果集中的对象。创建另一个线程允许当前线程返回到 WMI，而不会耗尽线程池。提供程序是否选择单线程设计而不是双线程设计取决于提供程序计划使用 WMI 线程的时间。没有固定的规则。试验可以帮助你确定设计如何影响 WMI 性能。

要求

要求	值
最低受支持的客户端	Windows Vista
最低受支持的服务器	Windows Server 2008
目标平台	Windows
标头	wbemcli.h (包括 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

另请参阅

调用方法

IWbemServices

IWbemServices::CreateInstanceEnum

通过