IOleAdviseHolder
COM公式ドキュメント
オブジェクトサーバー内でアドバイザリ接続と複合ドキュメントの通知を管理します。
メソッド 6
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
OLE オブジェクトと呼び出し側オブジェクトのアドバイズシンクとの間にアドバイザリ接続を確立します。このシンクを通じて、呼び出し側オブジェクトは OLE オブジェクトの名前変更、保存、またはクローズ時に通知を受け取ることができます。
| pAdvise | IAdviseSink* | in | 変更が通知されるべきアドバイザリシンク上の IAdviseSink インターフェイスへのポインター。 |
| pdwConnection | DWORD* | out | アドバイザリ接続を削除するために IOleAdviseHolder::Unadvise メソッドに渡すことができるトークンへのポインター。呼び出し側オブジェクトは、このポインターに対して IUnknown::AddRef と IUnknown::Release の両方を呼び出す責任があります。 |
戻り値
このメソッドは成功時に S_OK を返します。その他の可能な戻り値には次のものがあります。
| 戻り値 | 説明 |
|---|---|
| 指定された IAdviseSink インターフェイスポインターが無効です。 |
解説(Remarks)
コンテナー、オブジェクトハンドラー、リンクオブジェクトはいずれも、埋め込みオブジェクトやリンクオブジェクトなど関心のある複合ドキュメントオブジェクトの変更通知を受け取るためにアドバイズシンクを作成します。これらのオブジェクトにとって関心のある OLE オブジェクトは、IOleObject インターフェイスを実装する必要があります。これには IOleObject::Advise を含むいくつかのアドバイザリメソッドが含まれます。このメソッドの呼び出しは、それを呼び出す任意のアドバイズシンクとのアドバイザリ接続を確立し、各接続をクローズされるまで維持する必要があります。また、同時に複数のアドバイザリ接続を処理できる必要があります。
IOleAdviseHolder::Advise は、IOleObject::Advise の実装を簡略化するために使用することを意図しています。CreateOleAdviseHolder を呼び出すことで IOleAdviseHolder の OLE 実装へのポインターを取得でき、IOleObject::Advise を実装するには、その呼び出しを IOleAdviseHolder::Advise に委譲するだけで済みます。その他の IOleAdviseHolder メソッドは、その他の IOleObject アドバイザリメソッドを実装することを意図しています。
アドバイザリ接続の確立が成功した場合、呼び出しを受け取ったオブジェクトは pdwConnection を通じて非ゼロの値を返します。試行が失敗した場合、オブジェクトはゼロを返します。アドバイザリ接続を削除するには、アドバイズシンクを持つオブジェクトが、この非ゼロのトークンを IOleAdviseHolder::Advise の呼び出しを通じてオブジェクトに返します。
以前に確立されたアドバイザリ接続を削除します。(IOleAdviseHolder.Unadvise)
| dwConnection | DWORD | in | 以前に IOleAdviseHolder::Advise が pdwConnection で返した値。 |
戻り値
このメソッドは成功時に S_OK を返します。その他の可能な戻り値には次のものがあります。
| 戻り値 | 説明 |
|---|---|
| dwConnection パラメーターが有効なアドバイザリ接続を表していません。 |
解説(Remarks)
IOleAdviseHolder::Unadvise は、アドバイザリ接続を削除するための IOleObject::Unadvise を実装するために使用することを意図しています。一般的には、CreateOleAdviseHolder の呼び出しを通じてポインターを取得した OLE アドバイズホルダーを使用します。
通常、コンテナーはシャットダウン時やオブジェクトが削除されたときにこのメソッドを呼び出します。特定のケースでは、実行中だが現在表示されていないオブジェクトに対して、複数のアドバイザリ接続を維持するオーバーヘッドを削減する方法として、コンテナーがこのメソッドを呼び出すことがあります。
オブジェクトに対して現在確立されているアドバイザリ接続を列挙するために使用できる列挙子を作成します。
| ppenumAdvise | IEnumSTATDATA** | out | 新しい列挙子へのインターフェイスポインターを受け取る IEnumSTATDATA ポインター変数へのポインター。このパラメーターが NULL の場合、現在オブジェクトにアドバイザリ接続が存在しないか、エラーが発生したことを意味します。アドバイズホルダーは、このメソッドが提供する IEnumSTATDATA ポインターの参照カウントをインクリメントする責任があります。ポインターの使用を終えたときに IUnknown::Release を呼び出すのは呼び出し側の責任です。 |
戻り値
このメソッドは成功時に S_OK を返します。その他の可能な戻り値には次のものがあります。
| 戻り値 | 説明 |
|---|---|
| 列挙操作が失敗しました。 | |
|
IOleAdviseHolder::EnumAdvise が実装されていません。 |
解説(Remarks)
IOleAdviseHolder::EnumAdvise は、オブジェクトに確立されたアドバイザリ接続を列挙するために使用できる列挙子を作成します。このメソッドは、この列挙子上の IEnumSTATDATA インターフェイスへのポインターを提供します。各接続のアドバイザリ接続情報は STATDATA 構造体に格納され、列挙子はこれらの構造体を列挙できる必要があります。
このメソッドでは、関連する構造体メンバーは pAdvise と dwConnection のみです。その他のメンバーはデータアドバイザリ情報を含みます。列挙メソッドを呼び出したとき、および列挙の進行中に、列挙対象に対してアドバイザリ接続を登録または取り消した場合の影響は未定義です。
オブジェクトの名前が変更されたことを、アドバイズホルダーに現在登録されているすべてのアドバイザリシンクに通知します。
| pmk | IMoniker* | in | オブジェクトの新しいフルモニカーへのポインター。 |
戻り値
このメソッドは、アドバイズシンクに IAdviseSink::OnRename 通知が送信された場合に S_OK を返します。
解説(Remarks)
SendOnRename は IAdviseSink::OnRename を呼び出して、既にアドバイザリ接続を確立している呼び出し側オブジェクトに、オブジェクトが新しいモニカーを持つことを通知します。OLE アドバイズホルダーを使用している場合(CreateOleAdviseHolder の呼び出しを通じてポインターを取得している場合)、操作が成功したと判断したときに、IOleObject::SetMoniker の実装内で SendOnRename を呼び出すことができます。
オブジェクトが保存されたことを、アドバイズホルダーに現在登録されているすべてのアドバイザリシンクに通知します。
戻り値
このメソッドは、アドバイズシンクに IAdviseSink::OnSave 通知が送信された場合に S_OK を返します。
解説(Remarks)
SendOnSave は IAdviseSink::OnSave を呼び出して、既にアドバイザリ接続を確立している呼び出し側オブジェクト(クライアント)に、オブジェクトが保存されたことを通知します。OLE アドバイズホルダーを使用している場合(CreateOleAdviseHolder の呼び出しを通じてポインターを取得している場合)、アドバイズホルダーが関連付けられているオブジェクトを保存するたびに SendOnSave を呼び出すことができます。
オブジェクトを実行状態からロード状態にするには、クライアントが IOleObject::Close を呼び出します。その実装内で、ユーザーがオブジェクトを永続ストレージに保存したい場合、オブジェクトは IOleClientSite::SaveObject を呼び出し、続いて SendOnSave を呼び出します。
オブジェクトがクローズされたことを、アドバイズホルダーに現在登録されているすべてのアドバイザリシンクに通知します。
戻り値
このメソッドは、IAdviseSink::OnClose メソッドの呼び出しを通じてアドバイズシンクにクローズ操作が通知された場合に S_OK を返します。
解説(Remarks)
SendOnClose は、オブジェクトが実行状態からロード状態に移行するたびに、オブジェクトと有効なアドバイザリ接続を持つすべてのアドバイズシンクに対して IAdviseSink::OnClose を呼び出す必要があります。これは IOleObject::Close の呼び出しを通じて発生するため、クローズ操作が成功したと判断したときに SendOnClose を呼び出すことができます。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IOleAdviseHolder "{00000111-0000-0000-C000-000000000046}" #usecom global IOleAdviseHolder IID_IOleAdviseHolder "{}" #comfunc global IOleAdviseHolder_Advise 3 sptr,var #comfunc global IOleAdviseHolder_Unadvise 4 int #comfunc global IOleAdviseHolder_EnumAdvise 5 sptr #comfunc global IOleAdviseHolder_SendOnRename 6 sptr #comfunc global IOleAdviseHolder_SendOnSave 7 #comfunc global IOleAdviseHolder_SendOnClose 8 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IOleAdviseHolder "{00000111-0000-0000-C000-000000000046}" #usecom global IOleAdviseHolder IID_IOleAdviseHolder "{}" #comfunc global IOleAdviseHolder_Advise 3 sptr,sptr #comfunc global IOleAdviseHolder_Unadvise 4 int #comfunc global IOleAdviseHolder_EnumAdvise 5 sptr #comfunc global IOleAdviseHolder_SendOnRename 6 sptr #comfunc global IOleAdviseHolder_SendOnSave 7 #comfunc global IOleAdviseHolder_SendOnClose 8 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。