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

Статья
08/27/2023

Метод IWbemServices::ExecQueryAsync выполняет запрос для асинхронного извлечения объектов.

Синтаксис

HRESULT ExecQueryAsync(
  [in] const BSTR      strQueryLanguage,
  [in] const BSTR      strQuery,
  [in] long            lFlags,
  [in] IWbemContext    *pCtx,
  [in] IWbemObjectSink *pResponseHandler
);

Параметры

[in] strQueryLanguage

Допустимый BSTR , содержащий один из языков запросов, поддерживаемых инструментарием управления Windows (WMI). Это должно быть WQL.

[in] strQuery

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

Дополнительные сведения о создании строк запросов WMI см. в разделах Запросы с помощью WQL и Справочник по WQL .

[in] lFlags

Этот параметр может принимать одно из указанных ниже значений.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

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

WBEM_FLAG_BIDIRECTIONAL

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

WBEM_FLAG_SEND_STATUS

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

WBEM_FLAG_ENSURE_LOCATABLE

Этот флаг гарантирует, что возвращаемые объекты содержат достаточно сведений, чтобы системные свойства, такие как __PATH, __RELPATH и __SERVER, не имели значения NULL.

WBEM_FLAG_PROTOTYPE

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

WBEM_FLAG_DIRECT_READ

Этот флаг обеспечивает прямой доступ к поставщику для указанного класса без учета его родительского класса или подклассов.

[in] pCtx

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

[in] pResponseHandler

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

WMI вызывает AddRef к указателю только при возврате WBEM_S_NO_ERROR . Когда возвращается код ошибки, количество ссылок совпадает с числом ссылок для записи. Подробное описание асинхронных методов вызова см. в разделе Вызов метода.

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

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

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

Другие коды ошибок возвращаются в приемник объектов, заданный параметром pResponseHandler .

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

По завершении поставщик экземпляров может сообщить об успешном или неудачном выполнении с помощью кода возврата из ExecQueryAsync или посредством вызова SetStatus , выполненного через pResponseHandler. Если вы решили вызвать SetStatus, код возврата, отправляемый через pResponseHandler , имеет приоритет.

Существуют ограничения на количество ключевых слов AND и OR, которые можно использовать в WQL-запросах. Большое количество ключевых слов WQL, используемых в сложном запросе, может привести к возврату WMI кода ошибки WBEM_E_QUOTA_VIOLATION в качестве значения HRESULT . Ограничение ключевых слов WQL зависит от сложности запроса.

Метод IWbemObjectSink::Indicate вызывающего объекта может быть вызван для сообщения о прерывистом состоянии. Вызывается метод IWbemObjectSink::SetStatus , чтобы указать конец результирующих наборов.

Если поставщик не поддерживает обработку запросов, WMI может поддерживать его. Однако реализация обработки запросов поставщиком, вероятно, более эффективна, чем версия WMI. Для поддержки запросов поставщик экземпляров должен реализовать метод ExecQueryAsync . Если поставщик поддерживает ExecQueryAsync, WMI отправляет простой унарный запрос SELECT непосредственно поставщику через параметр strQuery , и поставщик должен проанализировать запрос и вернуть соответствующие экземпляры. Поставщик должен проанализировать запрос, так как WMI не изменяет запрос, даже если запрос написан на языке WQL.

Чтобы использовать WMI для обработки запросов, не устанавливайте свойство QuerySupportLevels в __InstanceProviderRegistration. При этом WMI вызывает реализацию CreateInstanceEnumAsync и выполняет фильтрацию результатов, чтобы вызывающий объект получал только те экземпляры, которые соответствуют критериям запроса.

В следующем примере показана типичная реализация execQueryAsync поставщика экземпляров. Вызывается метод IWbemObjectSink::SetStatus , чтобы указать конец результирующих наборов. Он также может вызываться без промежуточных вызовов IWbemObjectSink::Указывает , возникают ли ошибки.

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

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

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

// Parse the query.
//   You must implement ParseQuery().
    if (!ParseQuery(strQuery))  return WBEM_E_PROVIDER_NOT_CAPABLE;   

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

// Call a method to determine number of instances returned.
// You need to implement the GetNumberInst function.
    int iNumInst = GetNumberInst();

// Now loop through the private source and create each   
// instance which is part of the result set of the query.
    for (int iCnt = 0 ; iCnt < iNumInst ; iCnt++)
    {
// Prepare an empty object to receive the class definition.
         IWbemClassObject *pNextInst = 0;
         hRes = pClass->SpawnInstance(0, &pNextInst);

// Create the instance.
//   You must implement FillInst().
         /*FillInst(pNextInst, iCnt);*/ 

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

// Clean up memory
    pClass->Release();
  
// Send finish message to WMI.

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

    return hRes;
}

В предыдущем примере поставщик экземпляра получает поток из WMI для выполнения необходимых операций синхронизации. Можно вызвать метод AddRef приемника и создать другой поток для доставки объектов в результирующем наборе. Создание другого потока позволяет текущему потоку вернуться к WMI, не истощая пул потоков. Выбор поставщиком структуры одного потока или структуры с двумя потоками зависит от того, как долго поставщик планирует использовать поток WMI. Нет фиксированных правил. Эксперименты могут помочь определить, как ваша конструкция влияет на производительность WMI.

Примечание Когда поставщики реализуют ExecQueryAsync, они должны по умолчанию возвращать правильный результирующий набор на основе запроса. Если поставщик не может легко вернуть правильный результирующий набор, он может вернуть надмножество результатов и запросить выполнение WMI после фильтрации перед доставкой объектов клиенту, чтобы убедиться, что результирующий набор является правильным. Для этого поставщик вызывает SetStatus в приемнике, предоставленном в его реализации ExecQueryAsync , со следующими флагами.

// The pSink variable is of type IWbemObjectSink*
pSink->SetStatus(WBEM_STATUS_REQUIREMENTS,
    WBEM_REQUIREMENTS_START_POSTFILTER, 0, 0);

Примечание Все объекты, отправляемые впоследствии в службу WMI, фильтруются. Поставщик может отключить постфильтровку в середине потока с помощью следующего вызова.

// The pSink variable is of type IWbemObjectSink*
pSink->SetStatus(WBEM_STATUS_REQUIREMENTS, 
    WBEM_REQUIREMENTS_STOP_POSTFILTER, 0, 0);

Требования


Минимальная версия клиента	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