Win32 API 日本語リファレンス
ホーム › Storage.VirtualDiskService › IVdsAdviseSink

IVdsAdviseSink

COM
📘 Microsoft Learn (日本語) · English
IID8326cd1d-cf59-4936-b786-5efc08798e25継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

IVdsAdviseSink (vdshwprv.h) インターフェースは、VDS 通知を受信します。

解説(Remarks)

VDS は、プロバイダーが実装する IVdsProviderPrivate::OnLoad メソッドを呼び出すことにより、IVdsAdviseSink インターフェースをプロバイダーに登録します。

IVdsAdviseSink インターフェースを実装した後、アプリケーションは通知を受信するために、そのインターフェースを VDS に登録する必要があります。登録するには、IVdsService::Advise メソッドを呼び出し、IVdsAdviseSink インターフェースへのポインターを渡します。IVdsAdviseSink インターフェースの登録を解除して通知の受信を停止するには、IVdsService::Unadvise メソッドを使用します。

注意 Advise を呼び出したアプリケーションは、最終的に Unadvise を呼び出す必要があります。理想的には、通知を受信する必要がなくなった時点で、できるだけ早く Unadvise を呼び出すべきです。

アプリケーションを通知の受信対象として登録する際に、通知の種類やオブジェクトの種類を指定することはありません。むしろ、すべてのプロバイダーからのあらゆる種類の VDS 通知をすべて受信するように登録します。

メソッド 1

vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。

vtbl 3 HRESULT OnNotify(INT lNumberOfNotifications, VDS_NOTIFICATION* pNotificationArray)

IVdsAdviseSink::OnNotify メソッド (vdshwprv.h) は、プロバイダーから VDS へ、および VDS からアプリケーションへ通知を渡します。

lNumberOfNotificationsINTinpNotificationArray で指定される通知の数。
pNotificationArrayVDS_NOTIFICATION*inVDS_NOTIFICATION 構造体の配列へのポインター。プロバイダーがサービスを呼び出す場合は、プロバイダーがこの配列のメモリを割り当て、サービスがこの配列を解放します。サービスがアプリケーションを呼び出す場合は、VDS がこの配列を割り当てます。この場合、呼び出し側は CoTaskMemFree 関数を使用してこの配列を解放する必要があります。

戻り値

このメソッドは、E_INVALIDARG や E_OUTOFMEMORY などの標準的な HRESULT 値、および VDS 固有の戻り値 を返すことがあります。また、HRESULT_FROM_WIN32 マクロを使用して変換された システムエラーコード を返す場合もあります。エラーは、VDS 自体、または使用されている基盤の VDS プロバイダー から発生する可能性があります。返される可能性のある値には、次のものがあります。

戻り値 説明
S_FALSE
 プロバイダーがこのメソッドを呼び出したときにサービスが完全には初期化されていない場合、またはサービスによって一部の通知が失われた場合、VDS はこの値をプロバイダーに返します。

解説(Remarks)

アプリケーションは、VDS から通知を受信するためにこのメソッドを実装します。これらの通知の一部は VDS から発生しますが、その他は VDS によって転送されるプロバイダー通知です。

VDS は、サブシステムやコントローラーなど、すべての VDS オブジェクトのプロパティに関する情報のキャッシュを保持しています。通知を引き起こす変更が発生するたびに、このキャッシュは自動的に更新されます。また、VDS 通知に応答して IVdsHwProvider::Refresh または IVdsService::Refresh を呼び出すと、通知が際限なく送信されるループが発生する可能性があります。これらの理由から、アプリケーションはこのメソッドの実装内で IVdsHwProvider::Refresh または IVdsService::Refresh を呼び出すべきではありません。

このメソッドを使用して通知を送信するプロバイダーの場合、単一のイベントから発生する通知をまとめてグループ化することが推奨されます。たとえば、LUN が削除されたときには、影響を受けるすべてのドライブに対する VDS_NF_DRIVE_MODIFY 通知をまとめて送信します。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

HSP用 COM定義

#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。

出力引数: 
#define global IID_IVdsAdviseSink "{8326CD1D-CF59-4936-B786-5EFC08798E25}"
#usecom global IVdsAdviseSink IID_IVdsAdviseSink "{}"
#comfunc global IVdsAdviseSink_OnNotify  3 int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。