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

Статья
03/08/2023

Метод IWbemServices::GetObjectAsync извлекает объект ( определение класса или экземпляр) на основе его пути. Это похоже на IWbemServices::GetObject , за исключением того, что вызов возвращает немедленно, а объект предоставляется предоставленному приемнику объекта.

В настоящее время этот метод извлекает объекты только из пространства имен, связанного с указателем IWbemServices .

Синтаксис

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

Параметры

[in] strObjectPath

Путь к извлекаемого объекта. Для поставщика экземпляров StrObjectPath может иметь следующий формат:

Пространство имен:Class.Key = "Value"
Пространство имен:Class = "Value"
Пространство имен:Class.Key = "Value", Key2 = "Value2"

Указание пространства имен перед классом является необязательным. Пути к объектам без пространств имен относятся к экземплярам в текущем пространстве имен. При необходимости можно заменить символ с одной кавычками (') на символ двойной кавычки ("), чтобы разделять начало и конец строковых типов свойств.

Если значение равно NULL, возвращается пустой объект, который может стать новым классом. Дополнительные сведения см. в разделе Создание класса.

[in] lFlags

Следующие флаги влияют на поведение этого метода.

WBEM_FLAG_USE_AMENDED_QUALIFIERS

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

WBEM_FLAG_DIRECT_READ

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

WBEM_FLAG_SEND_STATUS

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

[in] pCtx

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

[in] pResponseHandler

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

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

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

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

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

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

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

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

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

Примеры

В следующем примере описывается реализация GetObjectAsync для поставщика экземпляров.

SCODE CInstPro::GetObjectAsync (BSTR ObjectPath, 
                                long lFlags, IWbemContext *pCtx,
                                IWbemObjectSink FAR* pHandler)
{
    ULONG cRef;         // Reference count
    SCODE sc;
    BOOL bOK = FALSE;

    IWbemServices *  m_pNamespace;
    IWbemClassObject FAR* pObj;

    // Check arguments.

    if(ObjectPath == NULL || pHandler == NULL ||
        m_pNamespace == NULL)
        return WBEM_E_INVALID_PARAMETER;

    
    // Based on the object path, produce an empty instance
    // of the class and gather required data,
    // setting the instance's property values accordingly.
    // This example assumes that GetByPath is implemented
    // by the provider to do this.
    // The IWbemPath interface can be used to parse
    // the object path, separating the namespace and class name.

    sc = GetByPath (ObjectPath, &pObj, pCtx);
    if(sc == S_OK) 
    {
        pHandler->Indicate (1, &pObj);
        pObj->Release();
        bOK = TRUE;
    }

    sc = (bOK) ? S_OK : WBEM_E_NOT_FOUND;

    // Set status.

    pHandler->SetStatus(0,sc, NULL, NULL);

    // Free memory resources.

    SysFreeString(ObjectPath);
    m_pNamespace->Release();
    pObj->Release();

    return sc;
  
}

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

HRESULT CStdProvider::GetObjectAsync( 
            /* [in] */ BSTR strObjectPath,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{

    IWbemClassObject *pClass = 0;

// Assume there is an IWbemServices pointer available.
// Retrieve an 'empty' object which is built up
// into the class definition.

    HRESULT hRes = m_pSvc->GetObject(NULL, 0, NULL, &pClass, 0);
    if (hRes)
        return hRes;

// Parse the object path and determine which class is   
// required. The path string is the required class name.
// Fill in the properties required for the class definition
// using pClass->Put(...), and so on.

    
    // ...

    // Send the class definition back to WMI.
    pResponseHandler->Indicate(1, &pClass);

// Indicate that it is now finished.

    pResponseHandler->SetStatus(0, WBEM_S_NO_ERROR, 0, 0);
    SysFreeString(strObjectPath);
    m_pSvc->Release();
    pClass->Release();  // This is no longer needed.
    return WBEM_S_NO_ERROR;
}

Требования

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