IAdviseSink

コンテナーやその他のオブジェクトが、対象となるオブジェクトで発生したデータの変更、ビューの変更、および複合ドキュメントの変更に関する通知を受け取れるようにします。

サーバーによって呼び出され、データオブジェクトに現在登録されているアドバイスシンクに対して、オブジェクト内のデータが変更されたことを通知します。

オブジェクトハンドラーおよびリンクオブジェクトのコンテナーは、オブジェクト内のデータが変更されたことを通知されたときに適切な処理を行うために IAdviseSink::OnDataChange を実装します。また、対象とするデータを持つオブジェクトとのアドバイザリ接続を確立するために、IDataObject::DAdvise を呼び出す必要があります。

OLE のキャッシュサポートを利用するコンテナーは、データ変更通知に登録する必要はありません。オブジェクトの表示(データの変更を含む)を更新するために必要な情報は、オブジェクトのキャッシュ内に保持されるためです。

実装者への注意事項

コンテナー向けに IAdviseSink::OnDataChange を実装する場合、このメソッドは非同期であり、非同期メソッド内で同期呼び出しを行うことは有効ではないことに注意してください。したがって、オブジェクトの更新に必要なデータを取得するために IDataObject::GetData を呼び出すことはできません。代わりに、内部メッセージをポストするか、InvalidateRect を呼び出して変更されたデータの矩形を無効化し、WM_PAINT メッセージを待ちます。そのメッセージを受け取った時点で、自由にデータを取得してオブジェクトを更新できます。

データ自体は呼び出しの間のみ有効であり、pStgmed が指すストレージメディアを使用して渡されます。メディアは呼び出し元が所有するため、アドバイスシンクはそれを解放してはなりません。また、pStgmed が IStorage または IStream インターフェイスを指している場合、シンクは参照カウントをインクリメントしてはなりません。

オブジェクトのビューが変更されたことを、登録されているアドバイスシンクに通知します。

コンテナーは、IViewObject::SetAdvise を呼び出すことで、オブジェクトのビューが変更されたときに通知を受け取るように登録します。登録後、オブジェクトは適切なタイミングでシンクの IAdviseSink::OnViewChange メソッドを呼び出します。OnViewChange は、オブジェクトがロード状態または実行状態のいずれにある場合でも呼び出される可能性があります。

DVASPECT の値は個別のフラグビットですが、dwAspect が表せる値は 1 つのみです。つまり、dwAspect には 2 つ以上の DVASPECT 値を OR 演算で組み合わせた結果を含めることはできません。

lindex パラメーターは、対象とするアスペクトの部分を表します。lindex の値は dwAspect の値に依存します。dwAspect が DVASPECT_THUMBNAIL または DVASPECT_ICON のいずれかである場合、lindex は無視されます。dwAspect が DVASPECT_CONTENT である場合、lindex は -1 でなければなりません。これはビュー全体を対象とすることを示し、現在有効な唯一の値です。

サーバーによって呼び出され、登録されているすべてのアドバイザリシンクに対して、オブジェクトの名前が変更されたことを通知します。

OLE リンクオブジェクトは通常、リンクソースまたはそのコンテナーの名前変更の通知を受け取るために IAdviseSink::OnRename を実装します。リンクソースとして機能するオブジェクトは OnRename を呼び出し、新しい完全なモニカーをオブジェクトハンドラーに渡します。オブジェクトハンドラーはこの通知をリンクオブジェクトに転送します。これに応じて、リンクオブジェクトは自身のモニカーを更新する必要があります。そしてリンクオブジェクトは、その通知を自身のコンテナーへ転送します。

サーバーによって呼び出され、登録されているすべてのアドバイザリシンクに対して、オブジェクトが保存されたことを通知します。

オブジェクトハンドラーおよびリンクオブジェクトは通常、オブジェクトが元のストレージへ(Save 操作によって)、または新しいストレージへ(Save As 操作によって)ディスクに保存されたときの通知を受け取るために IAdviseSink::OnSave を実装します。オブジェクトハンドラーおよびリンクオブジェクトは、キャッシュを更新する目的でオブジェクトの保存時に通知を受け取るように登録しますが、それは登録時に渡されるアドバイスフラグが ADVFCACHE_ONSAVE を指定している場合に限られます。オブジェクトハンドラーおよびリンクオブジェクトは、これらの通知を自身のコンテナーへ転送します。

サーバーによって呼び出され、登録されているすべてのアドバイザリシンクに対して、オブジェクトが実行状態からロード状態へ変化したことを通知します。

OnClose 通知は、オブジェクトが実行状態からロード状態へ移行しつつあることを示します。これにより、コンテナーは適切な手順で正常なシャットダウンを行うための措置を講じることができます。たとえば、オブジェクトハンドラーはオブジェクトへのポインターを解放する必要があります。

クローズしようとしているオブジェクトが、その OLE サーバーアプリケーションがサポートする最後の開いているオブジェクトである場合、アプリケーションもシャットダウンできます。

リンクオブジェクトの場合、オブジェクトがクローズしているという通知は、常にリンクソースへの接続が切断されたことを意味すると解釈すべきです。

#define global IID_IAdviseSink "{0000010F-0000-0000-C000-000000000046}"
#usecom global IAdviseSink IID_IAdviseSink "{}"
#comfunc global IAdviseSink_OnDataChange  3 var,var
#comfunc global IAdviseSink_OnViewChange  4 int,int
#comfunc global IAdviseSink_OnRename      5 sptr
#comfunc global IAdviseSink_OnSave        6
#comfunc global IAdviseSink_OnClose       7
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。