IDataAdviseHolder

COM

IID00000110-0000-0000-c000-000000000046継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

データオブジェクトと1つ以上のアドバイズシンクとの間のアドバイザリ接続を作成し、管理します。

メソッド 4

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

vtbl 3 HRESULT Advise(IDataObject* pDataObject, FORMATETC* pFetc, DWORD advf, IAdviseSink* pAdvise, DWORD* pdwConnection)

通知を受信するために、アドバイズシンクとデータオブジェクトとの間の接続を作成します。

pDataObject

IDataObject*

inoptional

通知を要求する対象のデータオブジェクト上の IDataObject インターフェイスへのポインターです。このオブジェクト内のデータが変更されると、通知を要求したアドバイズシンクに通知が送信されます。

pFetc

FORMATETC*

通知を要求するアドバイズシンクが関心を持つ、指定された形式、媒体、およびターゲットデバイスを含む FORMATETC 構造体へのポインターです。たとえば、あるシンクはデータオブジェクト内のデータのビットマップ表現が変更されたときだけを知りたい場合があります。別のシンクは同じオブジェクトのメタファイル形式だけに関心がある場合があります。各アドバイズシンクは、関心のあるデータが変更されたときに通知されます。このデータは、通知の発生時にアドバイズシンクへ渡されます。

advf

DWORD

アドバイザリ接続を制御するフラグのグループです。指定可能な値は ADVF 列挙型のものです。ただし、このメソッドに関係するのは指定可能な ADVF 値のうち一部のみです。次の表は関連する値を簡潔に説明します。より詳細な説明は ADVF 列挙型の説明にあります。

値	意味
ADVF_NODATA	通知とともにデータを送信しないよう要求します。
ADVF_ONLYONCE	最初の通知が送信された後にアドバイザリ接続を破棄させます。呼び出し元に代わって IDataAdviseHolder::Unadvise が暗黙的に呼び出され、接続が削除されます。
ADVF_PRIMEFIRST	データが現在の状態から変更されているかどうかにかかわらず、初回の通知を送信させます。
ADVF_DATAONSTOP	ADVF_NODATA とともに指定された場合、このフラグは、データオブジェクトが破棄される前に、データを含む最後の通知を送信させます。ADVF_NODATA が指定されていない場合、このフラグは効果を持ちません。

pAdvise

IAdviseSink*

変更通知を受信するアドバイザリシンク上の IAdviseSink インターフェイスへのポインターです。

pdwConnection

DWORD*

out

この接続を識別するトークンを受け取る変数へのポインターです。呼び出し元のオブジェクトは、後でこのトークンを IDataAdviseHolder::Unadvise に渡すことでアドバイザリ接続を削除できます。この値が0の場合、接続は確立されませんでした。

戻り値

このメソッドは成功時に S_OK を返します。

解説(Remarks)

このメソッドで確立された接続を通じて、アドバイザリシンクは IAdviseSink::OnDataChange の呼び出しで今後の通知を受信できます。

オブジェクトは、関心のある形式、媒体、またはターゲットデバイスの変更に関する通知を要求するために IDataObject::DAdvise を呼び出します。このデータは pFormatetc パラメーターで指定されます。DAdvise メソッドは通常、接続のセットアップと追跡のタスクをアドバイズホルダーに委譲するために IDataAdviseHolder::Advise を呼び出すように実装されます。対象の形式、媒体、またはターゲットデバイスが変更されると、データオブジェクトは IDataAdviseHolder::SendOnDataChange を呼び出して必要な通知を送信します。

確立された接続は、pdwConnection の値を IDataAdviseHolder::Unadvise の呼び出しに渡すことで削除できます。

vtbl 4 HRESULT Unadvise(DWORD dwConnection)

以前の IDataAdviseHolder::Advise の呼び出しで設定された、データオブジェクトとアドバイザリシンクとの間の接続を削除します。このメソッドは通常、IDataObject::DUnadvise の実装内で呼び出されます。

dwConnection

DWORD

削除する接続を指定するトークンです。この値は、接続が最初に確立されたときに IDataAdviseHolder::Advise によって返されたものです。

戻り値

このメソッドは成功時に S_OK を返します。その他に返される可能性のある値には次のものがあります。

戻り値	説明
OLE_E_NOCONNECTION	dwConnection パラメーターが有効な接続を指定していません。

vtbl 5 HRESULT EnumAdvise(IEnumSTATDATA** ppenumAdvise)

現在のアドバイザリ接続を列挙するために使用できるオブジェクトを返します。

ppenumAdvise

IEnumSTATDATA**

out

新しい列挙子オブジェクトへのインターフェイスポインターを受け取る IEnumSTATDATA ポインター変数へのポインターです。実装が *ppenumAdvise に NULL を返す場合、現時点ではアドバイズシンクへの接続はありません。

戻り値

このメソッドは、列挙子オブジェクトが正常にインスタンス化された場合、または接続が存在しない場合に S_OK を返します。

解説(Remarks)

このメソッドは IEnumSTATDATA インターフェイスの実装へのポインターを提供する必要があります。そのメソッドを使用すると、STATDATA 構造体の配列に格納されたデータを列挙できます。CreateDataAdviseHolder を呼び出して IDataAdviseHolder の OLE 実装へのポインターを取得し、次に IDataAdviseHolder::EnumAdvise を呼び出して IDataObject::EnumDAdvise を実装します。

列挙子オブジェクトがアクティブな間にさらにアドバイザリ接続を追加すると、このメソッドから得られる列挙結果に対して未定義の影響を及ぼします。

vtbl 6 HRESULT SendOnDataChange(IDataObject* pDataObject, DWORD dwReserved, DWORD advf)

このアドバイズホルダーオブジェクトのインスタンスで現在処理されている各アドバイズシンクに対して IAdviseSink::OnDataChange メソッドを呼び出すことにより、接続が確立されている各アドバイズシンクへ通知を送信します。

pDataObject	IDataObject*	in	データが変更されたばかりのデータオブジェクト上の IDataObject インターフェイスへのポインターです。このポインターは、後続の IAdviseSink::OnDataChange の呼び出しで使用されます。
dwReserved	DWORD	optional	このパラメーターは予約されており、0 でなければなりません。
advf	DWORD	in	IAdviseSink::OnDataChange の呼び出し方法を指定するアドバイズフラグのコンテナーです。これらのフラグ値は ADVF 列挙型のものです。通常、advf の値は NULL です。唯一の例外は、データオブジェクトがシャットダウン中で、IDataObject::DAdvise の呼び出しで ADVF_DATAONSTOP および ADVF_NODATA を指定したシンクへ、実際のデータを含む最終通知を送信する必要がある場合に発生します。この場合、advf には ADVF_DATAONSTOP が含まれます。

戻り値

このメソッドは成功時に S_OK を返します。

解説(Remarks)

データオブジェクトは、以前に通知を要求したアドバイズシンクが関心を持つであろう変更を検出したときに、このメソッドを呼び出す必要があります。

ほとんどの通知には実際のデータが含まれます。唯一の例外は、接続が最初に IDataAdviseHolder::Advise メソッドで設定されたときに ADVF_NODATA フラグが指定されていた場合です。

各アドバイズシンクに対して IAdviseSink::OnDataChange メソッドを呼び出す前に、このメソッドは pDataObject パラメーターで指定されたポインターを通じて IDataObject::GetData メソッドを呼び出すことで実際のデータを取得します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IDataAdviseHolder "{00000110-0000-0000-C000-000000000046}"
#usecom global IDataAdviseHolder IID_IDataAdviseHolder "{}"
#comfunc global IDataAdviseHolder_Advise            3 sptr,var,int,sptr,var
#comfunc global IDataAdviseHolder_Unadvise          4 int
#comfunc global IDataAdviseHolder_EnumAdvise        5 sptr
#comfunc global IDataAdviseHolder_SendOnDataChange  6 sptr,int,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IDataAdviseHolder "{00000110-0000-0000-C000-000000000046}"
#usecom global IDataAdviseHolder IID_IDataAdviseHolder "{}"
#comfunc global IDataAdviseHolder_Advise            3 sptr,sptr,int,sptr,sptr
#comfunc global IDataAdviseHolder_Unadvise          4 int
#comfunc global IDataAdviseHolder_EnumAdvise        5 sptr
#comfunc global IDataAdviseHolder_SendOnDataChange  6 sptr,int,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。