Метод IWbemServices::CreateInstanceEnumAsync (wbemcli.h)

Статья
08/27/2023

Метод IWbemServices::CreateInstanceEnumAsync создает перечислитель, который асинхронно возвращает экземпляры указанного класса в соответствии с заданными пользователем критериями выбора. Этот метод поддерживает простые запросы WMI Query Language (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 (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 вызывает AddRef только для указателя в тех случаях, когда возвращается WBEM_S_NO_ERROR . В случаях, когда возвращается код ошибки, количество ссылок совпадает с числом при записи. Дополнительные сведения см. в разделе Вызов метода.

Возвращаемое значение

Этот метод возвращает HRESULT , указывающий состояние вызова метода. В следующем списке перечислены значения, содержащиеся в HRESULT.

При сбое можно получить дополнительные сведения из функции COM GetErrorInfo.

Коды ошибок COM также могут возвращаться, если проблемы с сетью приводят к потере удаленного подключения к управлению Windows.

Поставщик экземпляра может сообщить об успешном или неудачном выполнении с помощью кода возврата из CreateInstanceEnumAsync или через вызов SetStatus , выполненный через pResponseHandler. Если вы решили вызвать 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
Header	wbemcli.h (включая Wbemidl.h)
Библиотека	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

Share via