IWbemServices::P utInstanceAsync メソッド (wbemcli.h)
IWbemServices::P utInstanceAsync メソッドは、既存のクラスのインスタンスを非同期的に作成または更新します。 更新の確認またはエラー報告は、呼び出し元によって実装された IWbemObjectSink インターフェイスを介して提供されます。
構文
HRESULT PutInstanceAsync(
[in] IWbemClassObject *pInst,
[in] long lFlags,
[in] IWbemContext *pCtx,
[in] IWbemObjectSink *pResponseHandler
);
パラメーター
[in] pInst
WMI リポジトリに書き込まれるインスタンスへのポインター。 呼び出し元は、この呼び出しの完了時に参照カウントについて想定できません。
[in] lFlags
インスタンスが現在存在しない場合に、呼び出し元がインスタンスを作成するかどうかを指定します。
インスタンス プロバイダーを実装する場合は、WBEM_E_PROVIDER_NOT_CAPABLEを返すことによって、lFlags で制限された数のフラグをサポートすることを選択できます。
このプロパティには、次の値を 1 つ以上指定できます。
WBEM_FLAG_CREATE_OR_UPDATE
このフラグを指定すると、このインスタンスが存在しない場合は作成されるか、既に存在する場合は上書きされます。
WBEM_FLAG_UPDATE_ONLY
既存のインスタンスを更新します。
WBEM_FLAG_CREATE_ONLY
このフラグは、インスタンスの作成専用です。 クラスが既に存在する場合、呼び出しは失敗します。
WBEM_FLAG_SEND_STATUS
このフラグは、 IWbemObjectSink::SetStatus のクライアント実装を通じて中間状態レポートを受信する要求を Windows Management に登録します。 プロバイダーの実装では、このフラグが動作を変更するための中間状態レポートをサポートする必要があります。
WBEM_FLAG_USE_AMENDED_QUALIFIERS
このフラグが設定されている場合、WMI は 修正された フレーバーを持つ修飾子を格納しません。 このフラグが設定されていない場合は、このオブジェクトがローカライズされていないと見なされ、すべての修飾子がこのインスタンスと共に格納されます。
[in] pCtx
クライアントが部分インスタンス更新または完全インスタンス更新を要求しているかどうかを示すポインター。 部分インスタンス更新では、インスタンスのプロパティのサブセットが変更されます。 これに対し、インスタンス全体を更新すると、すべてのプロパティが変更されます。 NULL の場合、このパラメーターは呼び出し元アプリケーションがインスタンス全体の更新を要求していることを示します。 それ以外の場合、これは、クラス インスタンスを生成する動的クラス プロバイダーに必要な IWbemContext オブジェクトへのポインターです。 このパラメーターの詳細については、「 WMI への呼び出しの作成」を参照してください。
[in] pResponseHandler
呼び出し元による IWbemObjectSink の実装へのポインター。 このハンドラーは、 IWbemObjectSink::SetStatus メソッドを使用して使用可能になったときに、この呼び出しの状態を受け取ります。 エラー コードが返された場合、指定された IWbemObjectSink ポインターは使用されません。 WBEM_S_NO_ERRORが返された場合、操作の結果を示すために、ユーザーの IWbemObjectSink 実装が呼び出されます。 Windows Management は、WBEM_S_NO_ERRORが返された場合にのみポインターに 対して AddRefを 呼び出します。 エラー コードが返された場合、参照カウントはエントリ時と同じです。 非同期呼び出しを行う方法の詳細については、「 メソッドの呼び出し」を参照してください。
戻り値
このメソッドは、メソッド呼び出しの状態を示す HRESULT を返します。 次の一覧は、 HRESULT 内に含まれる値の一覧です。
PutInstanceAsync がWBEM_S_NO_ERRORを返す場合、WMI は応答ハンドラーの SetStatus メソッドからの結果を待機します。 WMI は、ローカル接続で無期限に待機するか、リモート接続のタイムアウトが発生するまで待機します。
ネットワークの問題によって Windows Management へのリモート接続が失われると、COM 固有のエラー コードも返される可能性があります。
解説
PutInstanceAsync を呼び出すクライアントは、IWbemObjectSink::Indicate メソッドを使用して、呼び出しの結果が常に報告されることを期待する必要があります。
pInst が指すインスタンスが他のクラスから派生したクラスに属している場合、PutInstanceAsync の成功は、親クラスを担当するプロバイダーの成功によって異なります。 たとえば、pInst が ClassB に属し、ClassB が ClassA から派生している場合、ClassA のプロバイダーによって実装される PutInstanceAsync メソッドの呼び出しは、ClassB の更新操作が成功するために成功する必要があります。 詳細については、「 IWbemServices::P utInstance の備考」を参照してください。
インスタンス プロバイダーを実装するときに、インスタンスのキー プロパティが NULL に設定されている場合、 PutInstanceAsync はクラス内で一意であることが保証される値を選択する必要があります。 WMI が NULL キー プロパティを使用してインスタンスを更新する要求を処理すると、内部的に GUID が 生成され、キー プロパティに割り当てられます。 さらに、更新されるインスタンスが子クラスに属している場合、操作の成功は、階層内の上位のクラスを担当する各プロバイダーに対する PutInstanceAsync 呼び出しの成功に依存します。 他のすべてのプロバイダー が 成功するまで、WBEM_S_NO_ERRORを返さないでください。 詳細については、「 IWbemServices::P utInstance」を参照してください。
部分的な更新をサポートするインスタンス プロバイダーは、__PUT_EXTENSIONSコンテキスト値が存在するためにチェックする必要があります。 システム コンテキスト値は、特定の意味を持つ WMI によって定義される値であり、クライアント アプリケーションによって設定され、インスタンス プロバイダーによってサポートされます。 IWbemContext インターフェイスは、システム コンテキスト値とその他のプロバイダー固有のコンテキスト値へのアクセスを提供します。 次の一覧は、部分インスタンス更新操作をサポートするコンテキスト値の一覧です。
IWbemObjectSink::SetStatus メソッドは、結果セットの末尾を示すために呼び出されます。 また、 IWbemObjectSink::エラー 状態が発生したかどうかを示す呼び出しなしで呼び出すこともできます。
コールバックはクライアントが必要とするのと同じ認証レベルで返されない可能性があるため、非同期通信の代わりに半同期を使用することをお勧めします。 非同期通信が必要な場合は、「 メソッドの呼び出し」を参照してください。
メソッドを半同期的に使用する方法の詳細については、「 IWbemServices::P utInstance 」および「 メソッドの呼び出し」を参照してください。
| システム コンテキスト値 | 説明 |
|---|---|
|
__PUT_EXTENSIONS
(VT_BOOL) |
クライアント アプリケーションは、更新操作に関する詳細情報を提供するために、1 つ以上の他のシステム コンテキスト値を設定しています。 |
|
__PUT_EXT_STRICT_NULLS
(VT_BOOL) |
インスタンス プロバイダーは、必要に応じてプロパティの設定を 強制的にVT_NULL し、エラー発生時にエラーを発生させる必要があります。 |
|
__PUT_EXT_PROPERTIES
(VT_ARRAY | VT_BSTR) |
更新するプロパティの一覧が含まれます。 インスタンス プロバイダーは、他のすべてのプロパティを無視する必要があります。 |
|
__PUT_EXT_ATOMIC
(VT_BOOL) |
すべての更新が成功するか、インスタンス プロバイダーが元に戻す必要があります。 部分的な成功はあり得ません。 |
インスタンス プロバイダーを実装する場合は、pCtx の NULL プロパティに次の方法で応答する必要があります。
- プロパティの種類が VT_NULL場合、プロバイダーは変更を行わずにプロパティを無視するか、操作を失敗させることができます。
- プロパティの種類が VT_NULL されておらず、プロパティを更新できない場合、プロバイダーは新しい値でプロパティを更新する必要があるため、エラーを返す必要があります。
非同期操作を実装する場合、pResponseHandler で実行した AddRef を解放するまで、非同期操作は完了しません。 これは、pResponseHander で SetStatus を呼び出した場合でも発生します。 pResponseHandler がリークした場合、同期または半同期クライアントも完了せず、実装によっては応答を停止する可能性があります。
致命的なケースでも、分離されたプロバイダーの参照を解放する必要があります。 これは、同期と半同期の場合、WMI サービスは pResponseHandler の実装を所有しているためです。分離されたプロバイダーのプロセスが終了しても、クライアントは応答しません。
例
次の例では、 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;
}
要件
| サポートされている最小のクライアント | 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 |