IWbemServices

WMI サービスにアクセスするために、クライアントおよびプロバイダーが使用します。このインターフェイスは WMI と WMI プロバイダーによって実装され、WMI の中心となるインターフェイスです。

IWbemServices インターフェイスを実装するプロバイダーは、実装する各メソッドについて文書化されたセマンティクスに従う必要があります。また、プロバイダーは規定されたエラー戻りコードをサポートしなければなりません。WMI はすべてのメソッドを実装しますが、通常、各プロバイダーはこのインターフェイスで利用できる機能のごく一部だけを実装します。プロバイダーは、実装しないメソッドについては WBEM_E_PROVIDER_NOT_CAPABLE を返す必要があります。

IWbemServices の任意のメソッドから出力されるインターフェイスポインターは、そのメソッドを呼び出す前にすべて NULL に初期化しておく必要があります。たとえば、 IWbemServices::GetObject メソッドの呼び出しは IWbemClassObject インターフェイスポインターを返しますが、これは IWbemServices::GetObject メソッドを呼び出す前にあらかじめ NULL に初期化しておく必要があります。

例

IWbemServices を使用する C++ の例は多数あります。WMI C++ アプリケーションの例のセクションを参照してください。

次のコード例は、プロバイダーが IWbemServices ポインターを取得する方法を示しています。このコードをコンパイルするには、以下の #include 文と参照が必要です。

#include <iostream>
using namespace std;
#include <wbemidl.h>
#pragma comment(lib, "wbemuuid.lib")

IWbemLocator *pIWbemLocator = NULL;

HRESULT hRes = CoCreateInstance (
            CLSID_WbemAdministrativeLocator,
            NULL ,
            CLSCTX_INPROC_SERVER | CLSCTX_LOCAL_SERVER , 
            IID_IUnknown ,
            ( void ** ) &pIWbemLocator
            ) ;

IWbemServices *pWbemServices = NULL;

if (SUCCEEDED(hRes))
{
    BSTR namespace = SysAllocString(L"root\\CIMV2");
    hRes = pIWbemLocator->ConnectServer(
                namespace,      // Namespace
                NULL,           // Userid
                NULL,           // PW
                NULL,           // Locale
                0,              // flags
                NULL,           // Authority
                NULL,           // Context
                &pWbemServices
                );
    SysFreeString(namespace);            

    pIWbemLocator->Release(); // Free memory resources.

    // Use pWbemServices

}

// Clean up
pWbemServices->Release();

IWbemServices::OpenNamespace メソッドは、指定した子名前空間を操作コンテキストとする新しい IWbemServices ポインターを呼び出し元に提供します。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

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

IWbemLocator::ConnectServer メソッドでも同じ名前空間を開くことができます。唯一の違いは、 OpenNamespace メソッドでは Namespace パラメーターに相対オブジェクトパスを指定して子名前空間を再帰的に開けるのに対し、 IWbemLocator::ConnectServer では完全なオブジェクトパスが必要な点です。詳細については、 Describing a WMI Namespace Object Path を参照してください。

たとえば、 IWbemServices インターフェイスポインターに関連付けられている現在の名前空間が root である場合、Namespace パラメーターに Default を指定すると、root\default 名前空間にバインドされた新しいポインターが得られます。

名前空間は、Release が呼び出されて参照カウントが 0 (ゼロ) になった時点で閉じられます。

IWbemServices::CancelAsyncCall メソッドは、非同期メソッドに元々渡された IWbemObjectSink ポインターに基づいて、現在保留中の非同期呼び出しをキャンセルします。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

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

シンクへのコールバックが、クライアントが要求するのと同じ認証レベルで返されるとは限らないため、非同期通信ではなく半同期通信を使用することを推奨します。詳細については、Calling a Method を参照してください。IWbemObjectSink::Indicate または IWbemObjectSink::SetStatus の実装内から CancelAsyncCall を呼び出すと WMI の状態に影響を与える可能性があるため、推奨されません。

ExecMethodAsync のようなメソッド呼び出しの場合、キャンセルされるのは呼び出しのクライアント側だけです。実装しているプロバイダーには呼び出しがキャンセルされたことは通知されず、処理は最後まで実行されます。

非同期呼び出しの使用方法の詳細については、Making an Asynchronous Call with C++ および Receiving Asynchronous Event Notifications を参照してください。

例

CancelAsyncCall を使用する完全な例については、Example: Receiving Event Notifications Through WMI を参照してください。

HRESULT CProvider_IWbemServices :: CancelAsyncCall ( 
  
 IWbemObjectSink *a_Sink
)
{
 HRESULT t_Result = WBEM_E_NOT_AVAILABLE ;
 return t_Result ;
}

IWbemServices::QueryObjectSink メソッドを使用すると、呼び出し元は Windows Management がエクスポートする通知ハンドラーを取得できます。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

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

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

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

IWbemServices::GetObjectAsync メソッドは、パスに基づいてオブジェクト (クラス定義またはインスタンス) を取得します。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

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

インスタンスプロバイダーを実装する際は、PSDK の WMI セクションにあるオブジェクトパスパーサーのサンプルコードを使用してオブジェクトパスを解析し、クライアントがどのオブジェクトを要求しているかを判別してください。さらに、派生クラスをサポートするプロバイダーは、継承されたプロパティではなく、そのクラスのローカルプロパティの値だけを提供すれば十分です。継承されたプロパティの処理は、WMI が基底クラスのプロバイダーに要求します。

クラスプロバイダーを実装する場合、 GetObjectAsync は strObjectPath パラメーターに格納されたクラス名のオブジェクトパスを解析して、どのクラスが要求されているかを判別する必要があります。次に、 GetObjectAsync メソッドはクラスを動的に構築するか、プライベートキャッシュから取り出します。そして GetObjectAsync は、pResponseHandler パラメーターが指す IWbemObjectSink ポインターを使用して、そのクラスを WMI に送信します。結果セットの終わりを示すために IWbemObjectSink::SetStatus メソッドが呼び出されます。エラーが発生した場合は、 IWbemObjectSink::Indicate を一度も呼び出さずに SetStatus が呼び出されることもあります。

コールバックが、クライアントが要求するのと同じ認証レベルで返されるとは限らないため、非同期通信ではなく半同期通信を使用することを推奨します。非同期通信が必要な場合は、Calling a Method を参照してください。

メソッドを半同期で使用する方法の詳細については、IWbemServices::GetObject および Calling a Method を参照してください。

例

次の例は、インスタンスプロバイダー向けに 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;
}

IWbemServices::PutClass メソッドは、新しいクラスを作成するか、既存のクラスを更新します。pObject パラメーターで指定するクラスは、必要なすべてのプロパティ値が正しく初期化されている必要があります。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

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

IWbemServices::PutClassAsync メソッドは、新しいクラスを作成するか、既存のクラスを更新します。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

その他の状態コードやエラーコードは、pReponseHandler パラメーターで指定したオブジェクトシンクに報告されます。

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

なお、 PutInstanceAsync が WBEM_S_NO_ERROR を返した場合、WMI は応答ハンドラーの SetStatus メソッドからの結果を待機します。WMI は、ローカル接続では無期限に、リモート接続ではタイムアウトが発生するまで待機します。

WBEM_E_FAILED を返すと他のプロバイダーがクラスを作成する機会を失うため、このコードは、後で成功する可能性のある形でクラスプロバイダーが失敗した場合にのみ返すようにしてください。

特定のクラスに対して複数のクラスプロバイダーがインストールされている場合、WMI はどのクラスプロバイダーがそのクラスを作成できるかを判別できません。

結果セットの終わりを示すために IWbemObjectSink::SetStatus メソッドが呼び出されます。エラーが発生した場合は、 IWbemObjectSink::Indicate を一度も呼び出さずに呼び出されることもあります。

コールバックが、クライアントが要求するのと同じ認証レベルで返されるとは限らないため、非同期通信ではなく半同期通信を使用することを推奨します。非同期通信が必要な場合は、Calling a Method を参照してください。

メソッドを半同期で使用する方法の詳細については、 IWbemServices::PutClass および Calling a Method を参照してください。

例

次のコード例は、 PutClassAsync の簡単な実装を示しています。

HRESULT CStdProvider::PutClassAsync( 
            /* [in] */ IWbemClassObject __RPC_FAR *pObject,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
    // You must implement the ClassIsValid function yourself to
    // determine if the class contains a valid instance
   if (ClassIsValid(lFlags, pObject))
   {
       return WBEM_S_NO_ERROR;
   }

   return WBEM_E_PROVIDER_NOT_CAPABLE;   
}

IWbemServices::DeleteClass メソッドは、指定したクラスを現在の名前空間から削除します。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

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

IWbemServices::DeleteClassAsync メソッドは、指定したクラスを現在の名前空間から削除します。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

その他のすべての戻りコードは、pReponseHandler パラメーターで指定したオブジェクトシンクに SetStatus メソッドを通じて渡されます。クラスが存在しない場合や、ユーザーにクラスを削除する権限がない場合などのエラー状態はハンドラーに報告され、このメソッドの戻りコードには反映されません。

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

動的インスタンスプロバイダーがそのクラスに関連付けられている場合、そのプロバイダーは登録解除され、以後そのクラスに対して呼び出されなくなります。削除されたクラスから派生するクラスもすべて削除され、それらに関連付けられたプロバイダーも登録解除されます。クラスが削除されると、指定したクラスとそのサブクラスの残存する静的インスタンスもすべて削除されます。

クラスが動的クラスプロバイダーによって提供されている場合、削除が成功するかどうかは、そのプロバイダーがクラスの削除をサポートしているかどうかに依存します。

メソッドを半同期で使用する方法の詳細については、IWbemServices::DeleteClass および Calling a Method を参照してください。

IWbemServices::CreateClassEnum メソッドは、選択条件を満たすすべてのクラスの列挙子を返します。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

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

IWbemServices::CreateClassEnumAsync メソッドは、クラスプロバイダーがサポートするすべてのクラスの列挙を返します。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。失敗した場合は、COM 関数 GetErrorInfo から利用可能な情報を取得できます。ネットワークの問題により WMI へのリモート接続が失われた場合は、COM 固有のエラーコードが返されることもあります。なお、 CreateClassEnumAsync が WBEM_S_NO_ERROR を返した場合、WMI は応答ハンドラーの SetStatus メソッドからの結果を待機します。WMI は、ローカル接続では無期限に、リモート接続ではタイムアウトが発生するまで待機します。以下に、HRESULT に含まれる値を示します。

コールバックが、クライアントが要求するのと同じ認証レベルで返されるとは限らないため、非同期通信ではなく半同期通信を使用することを推奨します。非同期通信が必要な場合は、Calling a Method を参照してください。

メソッドを半同期で使用する方法の詳細については、IWbemServices::CreateClassEnum および Calling a Method を参照してください。

例

次のコード例は、 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 のパフォーマンスにどのような影響を与えるかを確認するとよいでしょう。

IWbemServices::PutInstance メソッドは、既存クラスのインスタンスを作成または更新します。インスタンスは WMI リポジトリに書き込まれます。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

アプリケーションおよびプロバイダーは、既存クラスのインスタンスを作成または更新するために PutInstance を呼び出します。pCtx パラメーターの設定方法に応じて、インスタンスのプロパティの一部またはすべてが更新されます。部分インスタンス更新をサポートする方法の詳細については、 IWbemServices::PutInstanceAsync を参照してください。部分インスタンス更新を要求する方法の詳細については、 Modifying an Instance Property を参照してください。

PutInstance メソッドがサポートするのは、インスタンスの作成と更新だけです。インスタンスの移動はサポートしません。つまり、呼び出し元は、兄弟クラス内の別のインスタンスと同じキーを持つインスタンスを pInst パラメーターに設定することはできません。たとえば、ClassA が ClassB と ClassC の基底クラスであるとします。ClassA はキーとして KeyProp プロパティを定義しており、ClassB には KeyProp が 1 に設定されたインスタンスがあります。KeyProp が 1 の ClassC のインスタンスを作成するには、アプリケーションはまず DeleteInstance を呼び出して ClassB のインスタンスを削除し、その後 PutInstance で ClassC のインスタンスを保存する必要があります。

pInst が指すインスタンスがサブクラスに属している場合、Windows Management は、そのサブクラスの派生元となるすべてのクラスを担当するプロバイダーを呼び出します。元の PutInstance 要求が成功するには、これらのプロバイダーがすべて成功する必要があります。階層の最上位クラスをサポートするプロバイダーが最初に呼び出されます。以降、最上位クラスのサブクラスへと呼び出しが続き、Windows Management が pInst の指すインスタンスを所有するクラスのプロバイダーに到達するまで、上から下へと進みます。

Windows Management は、インスタンスの子クラスのプロバイダーは呼び出しません。したがって、アプリケーションが継承されたプロパティの値を変更したい場合は、親クラスの対応するインスタンスではなく、子クラスの完全なインスタンスに対して PutInstance を呼び出す必要があります。

クラス階層に属するインスタンスを更新する場合、pInst パラメーターは、変更対象のプロパティを含むインスタンスを指している必要があります。たとえば、対象のインスタンスが ClassB に属しているとします。ClassB のインスタンスは ClassA から派生しており、ClassA はプロパティ PropA を定義しています。アプリケーションが ClassB のインスタンスにおける PropA の値を変更したい場合、pInst には ClassA のインスタンスではなく、その ClassB のインスタンスを設定する必要があります。

抽象クラスのインスタンスに対して PutInstance を呼び出すことは許可されていません。

IWbemServices::PutInstanceAsync メソッドは、既存クラスのインスタンスを非同期に作成または更新します。更新の確認またはエラー報告は、呼び出し元が実装する IWbemObjectSink インターフェイスを通じて提供されます。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

なお、 PutInstanceAsync が WBEM_S_NO_ERROR を返した場合、WMI は応答ハンドラーの SetStatus メソッドからの結果を待機します。WMI は、ローカル接続では無期限に、リモート接続ではタイムアウトが発生するまで待機します。

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

PutInstanceAsync を呼び出すクライアントは、呼び出しの結果が自身の IWbemObjectSink::Indicate メソッドを通じて報告されることを常に想定しておく必要があります。

pInst が指すインスタンスが他のクラスから派生したクラスに属している場合、 PutInstanceAsync が成功するかどうかは、親クラスを担当するプロバイダーの成否に依存します。たとえば、pInst が ClassB に属し、ClassB が ClassA から派生している場合、ClassB に対する更新操作が成功するには、ClassA のプロバイダーが実装する PutInstanceAsync メソッドの呼び出しが成功する必要があります。詳細については、 IWbemServices::PutInstance の「解説」を参照してください。

インスタンスプロバイダーを実装する際、インスタンスのキープロパティが NULL に設定されている場合、 PutInstanceAsync はクラス内で一意であることが保証される値を選択する必要があります。WMI は、キープロパティが NULL のインスタンスを更新する要求を処理する際、内部的に GUID を生成してキープロパティに割り当てます。さらに、更新対象のインスタンスが子クラスに属している場合、操作の成否は、階層内の上位クラスを担当する各プロバイダーへの PutInstanceAsync 呼び出しの成否に依存します。他のすべてのプロバイダーが成功したことを確認するまで、WBEM_S_NO_ERROR を返してはいけません。詳細については、 IWbemServices::PutInstance を参照してください。

部分更新をサポートするインスタンスプロバイダーは、__PUT_EXTENSIONS コンテキスト値が存在するかどうかを確認する必要があります。システムコンテキスト値とは、WMI が特定の意味を持つものとして定義し、クライアントアプリケーションが設定し、インスタンスプロバイダーがサポートする値です。 IWbemContext インターフェイスは、システムコンテキスト値およびその他のプロバイダー固有のコンテキスト値へのアクセスを提供します。以下に、部分インスタンス更新操作をサポートするコンテキスト値を示します。

結果セットの終わりを示すために IWbemObjectSink::SetStatus メソッドが呼び出されます。エラーが発生した場合は、 IWbemObjectSink::Indicate を一度も呼び出さずに呼び出されることもあります。

コールバックが、クライアントが要求するのと同じ認証レベルで返されるとは限らないため、非同期通信ではなく半同期通信を使用することを推奨します。非同期通信が必要な場合は、Calling a Method を参照してください。

メソッドを半同期で使用する方法の詳細については、IWbemServices::PutInstance および Calling a Method を参照してください。

インスタンスプロバイダーを実装する際は、pCtx 内の NULL プロパティに対して次のように対応してください。

• プロパティの型が VT_NULL の場合、プロバイダーはそのプロパティを変更せずに無視するか、操作を失敗させることができます。
• プロパティの型が VT_NULL でなく、そのプロパティを更新できない場合、プロバイダーは新しい値でプロパティを更新する義務があるため、エラーを返す必要があります。

非同期操作を実装する場合、pResponseHandler に対して行った AddRef をすべて解放するまで、その非同期操作は完了しません。これは、pResponseHander に対して SetStatus を呼び出した場合でも同様です。pResponseHandler がリークすると、実装によっては、同期クライアントや半同期クライアントも完了せず、応答を停止する可能性があります。

致命的な状況であっても、分離型プロバイダーでは参照を必ず解放する必要があります。これは、同期および半同期の場合、pResponseHandler の実装を WMI サービスが所有しているためです。分離型プロバイダーのプロセスが終了しても、クライアントは応答しないままになります。

例

次の例は、 PutInstanceAsync の構成方法を示しています。

HRESULT CStdProvider::PutInstanceAsync( 
            /* [in] */ IWbemClassObject __RPC_FAR *pInst,
            /* [in] */ long lFlags,
            /* [in] */ IWbemContext __RPC_FAR *pCtx,
            /* [in] */ IWbemObjectSink __RPC_FAR *pResponseHandler
            )
{
   // You must implement the InstanceIsValid method
   // to check to see if the instance in the pInst variable
   // is valid.
   if (InstanceIsValid(lFlags, pInst)) 
   {
       return WBEM_S_NO_ERROR;
   }

   return WBEM_E_PROVIDER_NOT_CAPABLE;   
}

IWbemServices::DeleteInstance メソッドは、現在の名前空間内にある既存クラスのインスタンスを削除します。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

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

IWbemServices::DeleteInstance メソッドは、現在の名前空間にある既存のインスタンスを削除するために呼び出します。他の名前空間のインスタンスは削除できません。階層内のクラスに属するインスタンスを削除するために DeleteInstance が呼び出されると、Windows Management は、その階層内の非抽象クラスを担当するすべてのプロバイダーに対して DeleteInstanceAsync メソッドを呼び出します。たとえば、strObjectPath パラメーターが ClassB のインスタンスを指しており、ClassB が非抽象クラスである ClassA から派生し、かつ同じく非抽象クラスである ClassC と ClassD の親クラスである場合、これら 4 つすべてのクラスのプロバイダーが呼び出されます。

Windows Management は、各プロバイダーのクラスを指すように修正したオブジェクトパスを使って、それぞれのプロバイダーを呼び出します。たとえば、元の呼び出しにおける strObjectPath が "ClassB.k=1" である場合、ClassA のプロバイダーへの呼び出しでは strObjectPath は "ClassA.k=1" に設定されます。

DeleteInstance 呼び出しの成否は、最上位の非抽象クラスのプロバイダーに対する DeleteInstanceAsync 呼び出しの成否のみに依存します。非抽象クラスとは、抽象クラスを親に持つクラスです。そうしたクラスのプロバイダーのいずれか 1 つでも成功すれば操作は成功し、すべてが失敗した場合に操作は失敗します。

たとえば、ClassX が次の階層の基底クラスであるとします。

1. ClassA は ClassX から派生します。
2. ClassB は ClassA から派生します。
3. ClassC と ClassD は ClassB から派生します。

ClassX、ClassA、ClassB がすべて抽象クラスであり、 DeleteInstance の strObjectPath パラメーターが同じく ClassB のインスタンスを指している場合は、ClassC のプロバイダーまたは ClassD のプロバイダーのいずれかが成功する必要があります。

IWbemServices::DeleteInstanceAsync メソッドは、現在の名前空間内にある既存クラスのインスタンスを非同期に削除します。操作の完了確認または失敗は、呼び出し元が実装する IWbemObjectSink インターフェイスを通じて報告されます。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

DeleteInstanceAsync が WBEM_S_NO_ERROR を返した場合、WMI は応答ハンドラーの SetStatus メソッドからの結果を待機します。WMI は、ローカル接続では無期限に、リモート接続ではタイムアウトが発生するまで待機します。

その他のエラー状態は、pResponseHandler パラメーターで指定したオブジェクトシンクに非同期に報告されます。

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

インスタンスプロバイダーは、 DeleteInstanceAsync の戻りコード、または pResponseHandler を通じた SetStatus の呼び出しのいずれかで、成功または失敗を報告できます。 SetStatus に送信した場合、pResponseHandler を通じてシンクに送られた戻りコードが優先されます。コールバックが、クライアントが要求するのと同じ認証レベルで返されるとは限らないため、非同期通信ではなく半同期通信を使用することを推奨します。非同期通信が必要な場合は、Calling a Method を参照してください。

メソッドを半同期で使用する方法の詳細については、IWbemServices::DeleteInstance および Calling a Method を参照してください。

IWbemServices::CreateInstanceEnum メソッドは、ユーザーが指定した選択条件に従って、指定クラスのインスタンスを返す列挙子を作成します。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

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

返された列挙子の要素数が 0 であっても、エラーではありません。

IWbemServices::CreateInstanceEnumAsync メソッドは、ユーザーが指定した選択条件に従って、指定クラスのインスタンスを非同期に返す列挙子を作成します。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

失敗した場合は、COM 関数 GetErrorInfo から詳細情報を取得できます。

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

インスタンスプロバイダーは、 CreateInstanceEnumAsync の戻りコード、または pResponseHandler を通じた SetStatus の呼び出しのいずれかで、成功または失敗を報告できます。 SetStatus を呼び出すことを選択した場合、pResponseHandler を通じて送られた戻りコードが優先されます。

CreateInstanceEnumAsync が WBEM_S_NO_ERROR を返した場合、WMI は応答ハンドラーの SetStatus メソッドからの結果を待機します。WMI は、ローカル接続では無期限に、リモート接続ではタイムアウトが発生するまで待機します。

結果セットの終わりを示すために IWbemObjectSink::SetStatus メソッドが呼び出されます。エラーが発生した場合は、 IWbemObjectSink::Indicate を一度も呼び出さずに呼び出されることもあります。

コールバックが、クライアントが要求するのと同じ認証レベルで返されるとは限らないため、非同期通信ではなく半同期通信を使用することを推奨します。

詳細については、IWbemServices::CreateInstanceEnum および Calling a Method を参照してください。

例

次の例は、 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 のパフォーマンスにどのような影響を与えるかを確認するとよいでしょう。

IWbemServices::ExecQuery メソッドは、オブジェクトを取得するためのクエリを実行します。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

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

IWbemServices::ExecQuery メソッドは、strQuery パラメーターで指定されたクエリを処理し、呼び出し元がクエリ結果にアクセスするための列挙子を作成します。列挙子は IEnumWbemClassObject インターフェイスへのポインターです。クエリ結果はクラスオブジェクトのインスタンスであり、 IWbemClassObject インターフェイスを通じて利用できます。

WQL クエリで使用できる "AND" および "OR" キーワードの数には上限があります。複雑なクエリで多数の WQL キーワードを使用すると、WMI が HRESULT 値として WBEM_E_QUOTA_VIOLATION エラーコードを返すことがあります。WQL キーワードの上限は、クエリの複雑さによって変わります。

IWbemServices::ExecQueryAsync メソッドは、オブジェクトを非同期に取得するためのクエリを実行します。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

失敗した場合は、COM 関数 GetErrorInfo から情報を取得できます。

その他のエラーコードは、pResponseHandler パラメーターで指定したオブジェクトシンクに返されます。

ネットワークの問題により WMI へのリモート接続が失われた場合は、COM 固有のエラーコードが返されることもあります。

処理完了時、インスタンスプロバイダーは、 ExecQueryAsync の戻りコード、または pResponseHandler を通じた SetStatus の呼び出しのいずれかで、成功または失敗を報告できます。 SetStatus を呼び出すことを選択した場合、pResponseHandler を通じて送られた戻りコードが優先されます。

WQL クエリで使用できる AND および OR キーワードの数には上限があります。複雑なクエリで多数の WQL キーワードを使用すると、WMI が HRESULT 値として WBEM_E_QUOTA_VIOLATION エラーコードを返すことがあります。WQL キーワードの上限は、クエリの複雑さによって変わります。

中間状態を報告するために、呼び出し元の IWbemObjectSink::Indicate メソッドが呼び出されることがあります。結果セットの終わりを示すために IWbemObjectSink::SetStatus メソッドが呼び出されます。

プロバイダーがクエリ処理をサポートしない場合は、WMI がこれを代行できます。ただし、通常はプロバイダー自身によるクエリ処理の実装のほうが、WMI による処理よりも効率的です。クエリをサポートするには、インスタンスプロバイダーが ExecQueryAsync メソッドを実装する必要があります。プロバイダーが ExecQueryAsync をサポートしている場合、WMI は単純な単項 SELECT クエリを strQuery パラメーターを通じてプロバイダーに直接送信し、プロバイダーはそのクエリを解析して該当するインスタンスを返す必要があります。WMI はクエリを一切変更しない (WQL で記述されたクエリであっても) ため、プロバイダー側で解析が必要になります。

クエリ処理に WMI を使用するには、__InstanceProviderRegistration の QuerySupportLevels プロパティを設定しないでください。そうすると、WMI は CreateInstanceEnumAsync の実装を呼び出し、その結果を事後フィルタリングして、クエリ条件を満たすインスタンスだけが呼び出し元に渡されるようにします。

次の例は、インスタンスプロバイダーによる ExecQueryAsync の典型的な実装を示しています。結果セットの終わりを示すために IWbemObjectSink::SetStatus メソッドが呼び出されます。エラーが発生した場合は、 IWbemObjectSink::Indicate を一度も呼び出さずに呼び出されることもあります。

コールバックが、クライアントが要求するのと同じ認証レベルで返されるとは限らないため、非同期通信ではなく半同期通信を使用することを推奨します。非同期通信が必要な場合は、Calling a Method を参照してください。

詳細については、IWbemServices::ExecQuery および Calling a Method を参照してください。

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 のパフォーマンスにどのような影響を与えるかを確認するとよいでしょう。

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

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

IWbemServices::ExecNotificationQuery メソッドは、イベントを受信するためのクエリを実行します。この呼び出しはすぐに戻り、ユーザーは返された列挙子をポーリングして、到着したイベントを取得できます。返された列挙子を解放すると、クエリはキャンセルされます。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

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

WQL クエリで使用できる AND および OR キーワードの数には上限があります。複雑なクエリで多数の WQL キーワードを使用すると、WMI が HRESULT 値として WBEM_E_QUOTA_VIOLATION エラーコードを返すことがあります。WQL キーワードの上限は、クエリの複雑さによって変わります。

IWbemServices::ExecNotificationQueryAsync メソッドは IWbemServices::ExecNotificationQuery と同じ処理を行いますが、イベント通知を停止するために CancelAsyncCall が呼び出されるまで、指定した応答ハンドラーにイベントが供給される点が異なります。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

その他のエラーコードは、pResponseHandler パラメーターで指定したオブジェクトシンクに返されます。

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

結果セットの終わりを示すために IWbemObjectSink::SetStatus メソッドが呼び出されます。エラーが発生した場合は、 IWbemObjectSink::Indicate を一度も呼び出さずに呼び出されることもあります。

コールバックが、クライアントが要求するのと同じ認証レベルで返されるとは限らないため、非同期通信ではなく半同期通信を使用することを推奨します。非同期通信が必要な場合は、Calling a Method を参照してください。

メソッドを半同期で使用する方法の詳細については、IWbemServices::ExecNotificationQuery および Calling a Method を参照してください。

WQL クエリで使用できる AND および OR キーワードの数には上限があります。複雑なクエリで多数の WQL キーワードを使用すると、WMI が HRESULT 値として WBEM_E_QUOTA_VIOLATION エラーコードを返すことがあります。WQL キーワードの上限は、クエリの複雑さによって変わります。

CIM オブジェクトがエクスポートするメソッドを実行します。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

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

ppOutParams が NULL でない場合、クライアントは ppOutParams が指すオブジェクトの ReturnValue プロパティを調べることで、メソッドの戻り値の型を判別できます。

CIM オブジェクトがエクスポートするメソッドを非同期に実行します。

このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。以下に、HRESULT に含まれる値を示します。

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

その他のエラーは、pReponseHandler パラメーターで指定したオブジェクトシンクに非同期に報告されます。

ネットワークの問題により WMI へのリモート接続が失われた場合は、COM 固有のエラーコードが返されることもあります。

1 つのメソッドプロバイダーが、多数のクラスやインスタンスにメソッドを提供できます。メソッドプロバイダーは、最大 3 種類の戻り値を扱う必要があります。

結果セットの終わりを示すために IWbemObjectSink::SetStatus メソッドが呼び出されます。エラーが発生した場合は、 IWbemObjectSink::Indicate を一度も呼び出さずに呼び出されることもあります。

コールバックが、クライアントが要求するのと同じ認証レベルで返されるとは限らないため、非同期通信ではなく半同期通信を使用することを推奨します。非同期通信が必要な場合は、Calling a Method を参照してください。

例

次の C++ の例は、TestMeth クラスの Echo メソッドに対して IWbemServices::ExecMethodAsync メソッドを実装する方法を示しています。TestMeth クラスは、入力パラメーターと出力パラメーターをそれぞれ 1 つ持ち、符号なし 32 ビット整数を返すメソッドをサポートしています。この実装では、Echo という名前のメソッドが 1 つだけ存在し、それを含むクラスも 1 つだけであることを前提としています。簡潔にするため、エラーチェックとオブジェクトパスの解析は行っていません。

STDMETHODIMP CMyMethodProvider::ExecMethodAsync(BSTR ObjectPath, 
    BSTR MethodName, long lFlags, IWbemContext* pCtx, 
    IWbemClassObject* pInParams, IWbemObjectSink* pResultSink)
{
    HRESULT hr;
    IWbemClassObject * pClass = NULL;
    IWbemClassObject * pOutClass = NULL;
    IWbemClassObject* pOutParams;

    // Allocate some BSTRs.

    BSTR ClassName = SysAllocString(L"TestMeth");    
    BSTR InputArgName = SysAllocString(L"sInArg");
    BSTR OutputArgName = SysAllocString(L"sOutArg");
    BSTR retValName = SysAllocString(L"ReturnValue");

    // Get the class object; this is hard-coded and matches the class
    // in the MOF.  A more sophisticated example would parse 
    // ObjectPath to determine the class and possibly the instance.
    // The m_pWbemSvcs pointer is of type IWbemServices*
    hr = m_pWbemSvcs->GetObject(ClassName, 0, pCtx, &pClass, NULL);

    // This method returns values, and so creates an instance of the
    // output argument class.

    hr = pClass->GetMethod(MethodName, 0, NULL, &pOutClass);
    pOutClass->SpawnInstance(0, &pOutParams);

    // Copy the input argument into the output object.

    VARIANT var;
    VariantInit(&var);

    // Get the input argument.
    pInParams->Get(InputArgName, 0, &var, NULL, NULL);   

    // Put it into the output object.
    pOutParams->Put(OutputArgName , 0, &var, 0);      

    long lLen = wcslen(var.bstrVal);
    VariantClear(&var);
    var.vt = VT_I4;
    var.lVal = lLen;
    // Special name for the return value.
    pOutParams->Put(retValName , 0, &var, 0); 

    // Send the output object back to the client by the sink. Then 
    // release the pointers and free the strings.

    hr = pResultSink->Indicate(1, &pOutParams);
    pOutParams->Release();
    pOutClass->Release();
    pClass->Release();
    SysFreeString(ClassName);
    SysFreeString(InputArgName);
    SysFreeString(OutputArgName);
    SysFreeString(retValName);
 
    // All done; now set the status.

    hr = pResultSink->SetStatus(0,WBEM_S_NO_ERROR,NULL,NULL);
    return WBEM_S_NO_ERROR;
}