IPropertyNotifySink
COM公式ドキュメント
IPropertyNotifySink をアウトゴーイングインターフェイスとしてサポートするオブジェクトから、プロパティ変更に関する通知を受け取るために、シンクオブジェクトによって実装されます。
解説(Remarks)
オブジェクト自身は、その型情報において [bindable] および [requestedit] 属性が付与されたプロパティに対してのみ、IPropertyNotifySink のメソッドを呼び出すことが求められます。オブジェクトが [bindable] プロパティを変更したときには、IPropertyNotifySink::OnChanged を呼び出す必要があります。オブジェクトが [requestedit] プロパティを変更しようとするときには、プロパティを変更する前に IPropertyNotifySink::OnRequestEdit を呼び出す必要があり、さらにこの呼び出しから戻る際にシンクが指定したアクションに従わなければなりません。
このルールの唯一の例外は、オブジェクトの初期化処理や読み込み処理の結果として通知が送信されないことです。初期化時には、すべてのプロパティが変更され、そのすべての変更が許可されるものと想定されます。したがって、このインターフェイスへの通知が意味を持つのは、完全に初期化・読み込みされたオブジェクトのコンテキストにおいてのみです。
メソッド 2
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
bindable プロパティが変更されたことをシンクに通知します。
| dispID | INT | in | 変更されたプロパティのディスパッチ識別子。複数のプロパティが変更された場合は DISPID_UNKNOWN を指定します。クライアント(シンクの所有者)は、通知を生成したオブジェクトから、関心のある各プロパティの現在の値を取得する必要があります。 |
戻り値
このメソッドはすべての場合において S_OK を返します。
解説(Remarks)
シンクが [bindable] プロパティを必要としない場合や、その他の何らかの失敗が発生した場合でも、すべての場合において S_OK が返されます。要するに、呼び出し元のオブジェクトは単に通知を送信するだけであり、エラーコード(E_NOTIMPL など)を用いて今後通知を送信しないかどうかを判断しようとすることはできません。そのようなセマンティクスは、このインターフェイスの一部ではありません。
requestedit プロパティが変更されようとしていることをシンクに通知します。
| dispID | INT | in | 変更されようとしているプロパティのディスパッチ識別子。複数のプロパティが変更されようとしている場合は DISPID_UNKNOWN を指定します。 |
戻り値
このメソッドは次の値を返すことがあります。
| Return code | Description |
|---|---|
| 指定されたプロパティの変更が許可されます。 | |
| 指定されたプロパティの変更は許可されません。呼び出し元は、新しいプロパティ値を破棄することでこの戻り値に従わなければなりません。これは [requestedit] 属性とこのメソッドのコントラクトの一部です。 |
解説(Remarks)
シンクは、変更を許可するか拒否するかを選択できます。たとえば、シンクはプロパティに読み取り専用の状態を強制することができます。DISPID_UNKNOWN は、複数のプロパティが変更されようとしていることを示すためにこのメソッドへの有効なパラメーターとなります。この場合、シンクはオブジェクト内のすべての [requestedit] プロパティに対して、シンクが個別に認識している特定のプロパティも含め、グローバルな読み取り専用状態を強制できます。
シンクが変更を許可する場合、オブジェクトは [requestedit] に加えて [bindable] が付与されたすべてのプロパティについても IPropertyNotifySink::OnChanged 通知を行う必要があります。
このメソッドは、いかなる種類のデータ検証の実装にも使用できません。呼び出しの時点では、プロパティの新しい値はまだ利用できないため、検証することができません。このメソッドの唯一の目的は、シンクがプロパティに読み取り専用の状態を強制できるようにすることです。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IPropertyNotifySink "{9BFBBC02-EFF1-101A-84ED-00AA00341D07}"
#usecom global IPropertyNotifySink IID_IPropertyNotifySink "{}"
#comfunc global IPropertyNotifySink_OnChanged 3 int
#comfunc global IPropertyNotifySink_OnRequestEdit 4 int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。