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

Статья
08/27/2023

Метод IWbemServices::CreateClassEnumAsync возвращает перечисление всех классов, поддерживаемых поставщиком классов. Поставщик класса создает каждое определение класса с нуля и возвращает только подклассы запрошенного класса. Как асинхронный метод CreateClassEnumAsync немедленно возвращает сообщение о состоянии, а затем при необходимости обновляет приемник, передаваемый через параметр pResponseHandler .

При успешном вызове WMI вызывает AddRef для указателя pResponseHandler, возвращает немедленно, а затем асинхронно вызывает pResponseHandler — >Indicate из другого потока с определениями классов до тех пор, пока запрос не будет удовлетворен.

Синтаксис

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

Параметры

[in] strSuperclass

Если значение не равно NULL или пустое значение, этот параметр задает имя родительского класса. В перечислителе возвращаются только классы, которые являются подклассами этого класса. Если значение NULL или пусто, а lFlags— WBEM_FLAG_SHALLOW, возвращаются только классы верхнего уровня, не имеющие родительского класса. Если значение равно NULL или пусто, а lFlagsWBEM_FLAG_DEEP, возвращаются все классы в пространстве имен.

[in] lFlags

Одно или несколько из следующих значений являются допустимыми.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

Если этот флаг установлен, инструментарий управления Windows (WMI) извлекает измененные квалификаторы, хранящиеся в локализованном пространстве имен текущего языкового стандарта подключения. Если значение не задано, извлекаются только квалификаторы, хранящиеся в непосредственном пространстве имен.

WBEM_FLAG_BIDIRECTIONAL

Этот флаг заставляет WMI сохранять указатели на объекты перечисления до тех пор, пока клиент не отпустит перечислитель.

WBEM_FLAG_DEEP

Этот флаг заставляет перечисление включать этот и все подклассы в иерархию.

WBEM_FLAG_SHALLOW

Этот флаг заставляет перечисление включать только чистые экземпляры этого класса, исключая все экземпляры подклассов, которые предоставляют свойства, не найденные в этом классе.

WBEM_FLAG_SEND_STATUS

Этот флаг регистрирует запрос в WMI на получение промежуточных отчетов о состоянии с помощью клиентской реализации IWbemObjectSink::SetStatus. Реализация поставщика должна поддерживать промежуточные отчеты о состоянии для этого флага, чтобы изменить поведение.

Примечание Если параметр strSuperclass имеет значение NULL или пустой и указан WBEM_FLAG_DEEP , возвращаются все классы.

[in] pCtx

Как правило, значение NULL. В противном случае это указатель на объект IWbemContext , который может использоваться поставщиком, возвращающим запрошенные классы. Значения в объекте контекста должны быть указаны в документации для поставщика. Дополнительные сведения об этом параметре см. в статье Вызовы WMI.

[in] pResponseHandler

Указатель на реализацию вызывающего объекта IWbemObjectSink. Этот обработчик получает объекты по мере их доступности с помощью метода IWbemObjectSink::Indicate . Если нет доступных объектов, метод IWbemObjectSink::SetStatus вызывается WMI. Если возвращается какой-либо код ошибки, предоставленный указатель IWbemObjectSink не используется. Если возвращается WBEM_S_NO_ERROR, вызывается пользовательская реализация IWbemObjectSink для указания результата операции. WMI вызывает AddRef только для указателя, когда возвращается WBEM_S_NO_ERROR . При возврате кода ошибки число ссылок совпадает с числом ссылок без записи. Подробное описание этого параметра см. в разделе Вызов метода .

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

Этот метод возвращает HRESULT , указывающий состояние вызова метода. При сбое можно получить доступную информацию из функции COM GetErrorInfo. Коды ошибок, относящиеся к COM, могут быть возвращены, если проблемы с сетью приводят к потере удаленного подключения к WMI. Обратите внимание, что если CreateClassEnumAsync возвращает WBEM_S_NO_ERROR, WMI ожидает результата от метода SetStatus обработчика ответа. WMI ожидает неограниченное время при локальном подключении или до истечения времени ожидания удаленного подключения. В следующем списке перечислены значения, содержащиеся в HRESULT.

Так как обратный вызов может быть возвращен не на том же уровне проверки подлинности, который требуется клиенту, рекомендуется использовать полусинхронный режим вместо асинхронного взаимодействия. Если требуется асинхронное взаимодействие, см. статью Вызов метода .

Дополнительные сведения об использовании методов полусинхронно см. в разделах IWbemServices::CreateClassEnum и Вызов метода.

Примеры

В следующем примере кода показано, как реализовать CreateClassEnumAsync.

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

    // Assume there is an IWbemServices pointer available (m_pSvc).
    // Retrieve an 'empty' object that will be built up
    // into the class definition.
    
    HRESULT hRes = m_pSvc->GetObject(NULL, 0, NULL, &pClass, 0);
    if (hRes)
    {
        return hRes;
    }

    // Prepare an empty object to receive the class definition.
        IWbemClassObject *pNextClass = 0;
        hRes = pClass->Clone(&pNextClass);

    // Now loop through the private source of class definitions
    // and create each class.
    while(hRes)
    {
        // Create the class definition elsewhere.
        // For example, call a function that creates a definition:
        // FillClassDef(pNextClass);

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

        // Prepare an empty object to receive the class definition.
        IWbemClassObject *pNextClass = 0;
        hRes = pClass->Clone(&pNextClass);     
    }

    pClass->Release();

    // Send a finish message to WMI.

    pResponseHandler->SetStatus(0, hRes, 0, 0);

    return hRes;
}

В предыдущем примере поставщик класса получает поток из 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