IWbemServices::GetObjectAsync メソッド (wbemcli.h)

[アーティクル]
08/27/2023

IWbemServices::GetObjectAsync メソッドは、パスに基づいて、クラス定義またはインスタンスのオブジェクトを取得します。これは IWbemServices::GetObject に似ていますが、呼び出しがすぐに返され、指定されたオブジェクトシンクにオブジェクトが提供される点が除きます。

現在、このメソッドは IWbemServices ポインターに関連付けられている名前空間からのみオブジェクトを取得します。

構文

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

パラメーター

[in] strObjectPath

取得するオブジェクトのパス。インスタンスプロバイダーの場合、 StrObjectPath は次の形式にすることができます。

Namespace:Class.Key = "Value"
Namespace:Class = "Value"
Namespace: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 Management は、 WBEM_S_NO_ERROR が返された場合にのみ AddRef をポインターに呼び出します。エラーコードが返された場合、参照カウントはエントリ時と同じです。このパラメーターの詳細については、「メソッドの呼び出し」を参照してください。

戻り値

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。次の一覧は、 HRESULT 内に含まれる値の一覧です。

失敗した場合は、COM 関数 GetErrorInfoGetErrorInfo から使用可能な情報を取得できます。

ネットワークの問題によって Windows Management へのリモート接続が失われる場合は、COM 固有のエラーコードも返される可能性があります。

注釈

インスタンスプロバイダーを実装する場合は、PSDK の WMI セクションにあるオブジェクトパスパーサーサンプルコードを使用して、クライアントが要求するオブジェクトを認識するためのオブジェクトパスを解析する必要があります。さらに、派生クラスをサポートするプロバイダーは、継承されたプロパティではなく、クラスのローカルプロパティの値のみを指定する必要があります。 WMI は、基底クラスのプロバイダーが継承されたプロパティを処理することを要求します。

クラスプロバイダーを実装する場合、 GetObjectAsync は 、strObjectPath パラメーターに格納されているクラス名オブジェクトパスを解析することによって、要求されているクラスを決定する必要があります。 GetObjectAsync メソッドは、クラスを動的にビルドするか、プライベートキャッシュからクラスを取得します。次に、GetObjectAsync は、pResponseHandler パラメーターによって指される IWbemObjectSink ポインターを使用して WMI にクラスを送信します。 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
ヘッダー	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