IRowsetEvents

COM

IID1551aea5-5d66-4b11-86f5-d5634cb211b9継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

イベント通知を受け取るためのメソッドを公開します。

解説(Remarks)

実装するタイミング

プロバイダーがロウセットのイベント通知を受け取る必要がある場合は、IRowsetEvents を実装します。IRowsetEvents はイベント通知を受け取るためのメソッドを公開しており、次のイベント通知を受け取るには実装が必要です: OnChangedItem、OnDeletedItem、OnNewItem、OnRowsetEvent。ROWSETEVENT_ITEMSTATE 列挙型はアイテムの状態を、ROWSETEVENT_TYPE 列挙型はロウセットイベントを、それぞれ表します。

インデクサーのイベント機能は Windows 7 で導入された新機能で、プロバイダーが自身のロウセットに関する通知を受け取れるようにします。プロバイダーはイベント機能を利用して、実際のファイルシステム上の場所と同様に振る舞うようにロウセットを維持できます。

IRowsetEvents インターフェイスは、開かれたインデクサーのロウセットに対してコネクションポイントによって登録されます。

ロウセットのイベント機能を使用するには、クエリを実行する前に OLE DB の ICommandProperties::SetProperties メソッドで DBPROP_ENABLEROWSETEVENTS を TRUE に設定しておく必要があります。

メソッド 4

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

vtbl 3 HRESULT OnNewItem(PROPVARIANT* itemID, ROWSETEVENT_ITEMSTATE newItemState)

クライアントのロウセットの条件の一部(またはすべて)に一致する可能性のある新しいアイテムをクライアントに通知するために、インデクサーによって呼び出されます。

itemID	PROPVARIANT*	in	ロウセットの元の検索条件に一致する可能性のある新しいアイテム。
newItemState	ROWSETEVENT_ITEMSTATE	in	新しいアイテムがロウセットの条件のすべてに一致するか一部に一致するかを、ROWSETEVENT_ITEMSTATE 列挙型で指定します。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

ROWSETEVENT_ITEMSTATE は、新しいアイテムがロウセットの元の検索条件にどの程度一致する可能性があるかを示します。

ROWSETEVENT_ITEMSTATE_INROWSET は、新しいアイテムがロウセットのすべての条件に確実に一致することを示します。
ROWSETEVENT_ITEMSTATE_UNKNOWN は、新しいアイテムがロウセットの条件の一部に少なくとも部分的に一致することを示します。完全に一致する場合もあります。
ROWSETEVENT_ITEMSTATE_NOTINROWSET は、新しいアイテムには適用されません。

vtbl 4 HRESULT OnChangedItem(PROPVARIANT* itemID, ROWSETEVENT_ITEMSTATE rowsetItemState, ROWSETEVENT_ITEMSTATE changedItemState)

アイテムが変更されたことをクライアントに通知するために、インデクサーによって呼び出されます。このアイテムは、クライアントのロウセットの条件の一部(またはすべて)に一致していた可能性があります。

itemID	PROPVARIANT*	in	ロウセット内で変更されたアイテムを指定します。
rowsetItemState	ROWSETEVENT_ITEMSTATE	in	変更されたアイテムが元々ロウセットに含まれていたかどうかを指定します。
changedItemState	ROWSETEVENT_ITEMSTATE	in	変更の結果として、変更されたアイテムが現在ロウセットに含まれているかどうかを指定します。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

rowsetItemState の ROWSETEVENT_ITEMSTATE は、そのアイテムが元のロウセットに含まれていたかどうかを示します。

ROWSETEVENT_ITEMSTATE_INROWSET は、アイテムがロウセットに確実に含まれていることを示します。
ROWSETEVENT_ITEMSTATE_UNKNOWN は、アイテムがロウセットに含まれている可能性があることを示します。ロウセットが完全には評価されていないため、含まれているかどうかは不明です。
ROWSETEVENT_ITEMSTATE_NOTINROWSET は、アイテムが元々ロウセットに含まれていなかったことを示します。

changedItemState の ROWSETEVENT_ITEMSTATE は、変更後のアイテムがロウセットの元の検索条件にどの程度一致するようになったかを示します。

ROWSETEVENT_ITEMSTATE_INROWSET は、アイテムが確実にロウセットに属することを示します。
ROWSETEVENT_ITEMSTATE_UNKNOWN は、アイテムがロウセットに属する可能性があることを示します。
ROWSETEVENT_ITEMSTATE_NOTINROWSET は、アイテムがロウセットに属さないことを示します。

vtbl 5 HRESULT OnDeletedItem(PROPVARIANT* itemID, ROWSETEVENT_ITEMSTATE deletedItemState)

アイテムが削除されたことをクライアントに通知するために、インデクサーによって呼び出されます。このアイテムは、クライアントのロウセットの検索条件の一部(またはすべて)に一致していた可能性があります。

itemID	PROPVARIANT*	in	ロウセット内で削除されたアイテムを指定します。
deletedItemState	ROWSETEVENT_ITEMSTATE	in	削除されたアイテムが現在ロウセットに含まれているかどうかを、ROWSETEVENT_ITEMSTATE 列挙型で指定します。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

ROWSETEVENT_ITEMSTATE は、そのアイテムが元のロウセットに含まれていたかどうかを示します。

ROWSETEVENT_ITEMSTATE_INROWSET は、削除されたアイテムが確実にロウセットに含まれていることを示します。
ROWSETEVENT_ITEMSTATE_UNKNOWN は、削除されたアイテムがロウセットに含まれている可能性があることを示します。ロウセットが完全には評価されていないため、含まれているかどうかは不明です。
ROWSETEVENT_ITEMSTATE_NOTINROWSET は、削除されたアイテムが元のロウセットには確実に含まれていなかったことを示します(ただし、OnNewItem または OnChangedItem イベントで既に通知されている場合があります)。

vtbl 6 HRESULT OnRowsetEvent(ROWSETEVENT_TYPE eventType, PROPVARIANT* eventData)

クライアントのロウセットに関連するイベントをクライアントに通知するために、インデクサーによって呼び出されます。

eventType	ROWSETEVENT_TYPE	in	通知のきっかけとなったイベントを ROWSETEVENT_TYPE 列挙型で表したものです。
eventData	PROPVARIANT*	in	そのイベント種別に対して想定されるイベントデータの値です。

戻り値

型: HRESULT

このメソッドが成功すると S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_IRowsetEvents "{1551AEA5-5D66-4B11-86F5-D5634CB211B9}"
#usecom global IRowsetEvents IID_IRowsetEvents "{}"
#comfunc global IRowsetEvents_OnNewItem      3 var,int
#comfunc global IRowsetEvents_OnChangedItem  4 var,int,int
#comfunc global IRowsetEvents_OnDeletedItem  5 var,int
#comfunc global IRowsetEvents_OnRowsetEvent  6 int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IRowsetEvents "{1551AEA5-5D66-4B11-86F5-D5634CB211B9}"
#usecom global IRowsetEvents IID_IRowsetEvents "{}"
#comfunc global IRowsetEvents_OnNewItem      3 sptr,int
#comfunc global IRowsetEvents_OnChangedItem  4 sptr,int,int
#comfunc global IRowsetEvents_OnDeletedItem  5 sptr,int
#comfunc global IRowsetEvents_OnRowsetEvent  6 int,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。