ホーム › System.WindowsSync › ISyncChangeBatchBase

ISyncChangeBatchBase

COM

IID52f6e694-6a71-4494-a184-a8311bf5d227継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

一連の変更のメタデータを表します。(ISyncChangeBatchBase)

解説(Remarks)

ISyncChangeBatchBase は変更バッチの基本インターフェイスです。通常は派生インターフェイスによってオーバーライドされます。たとえば、ナレッジ同期の場合は ISyncChangeBatch、完全列挙同期の場合は ISyncFullEnumerationChangeBatch です。

メソッド 14

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

vtbl 3 HRESULT GetChangeEnumerator(IEnumSyncChanges** ppEnum)

この変更バッチ内のアイテム変更を列挙する IEnumSyncChanges オブジェクトを取得します。

ppEnum

IEnumSyncChanges**

out

この変更バッチ内のアイテム変更を含む列挙子を返します。

戻り値

戻り値として考えられるコードには、次の表に示す値が含まれますが、これらに限定されません。

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	ポインターが無効です。
E_OUTOFMEMORY

vtbl 4 HRESULT GetIsLastBatch(BOOL* pfLastBatch)

この変更バッチ内の変更が同期セッションの最後のバッチであるかどうかを示すフラグを取得します。

pfLastBatch

BOOL*

inout

このバッチが最後のバッチであるかどうかを示すフラグを返します。

戻り値

戻り値として考えられるコードには、次の表に示す値が含まれますが、これらに限定されません。

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	pfLastBatch が NULL です。

解説(Remarks)

IKnowledgeSyncProvider::GetChangeBatch メソッドに応答して変更バッチを返す際、その変更バッチが最後の変更バッチである場合、ソースプロバイダーは SetLastBatch を呼び出す必要があります。

vtbl 5 HRESULT GetWorkEstimateForBatch(DWORD* pdwWorkForBatch)

バッチの作業量の見積もりを取得します。

pdwWorkForBatch

DWORD*

inout

バッチの作業量の見積もりを返します。既定値は 0 です。

戻り値

戻り値として考えられるコードには、次の表に示す値が含まれますが、これらに限定されません。

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	ポインターが無効です。

解説(Remarks)

作業量の見積もりはプロバイダーによって決定され、通常は単一のバッチ内のすべての変更に対する総作業量であり、かつセッション全体で見積もられた作業量の一部として解釈されます。

この値は OnProgress イベントで報告されます。

vtbl 6 HRESULT GetRemainingWorkEstimateForSession(DWORD* pdwRemainingWorkForSession)

セッションの残り作業量の見積もりを取得します。

pdwRemainingWorkForSession

DWORD*

inout

セッションの残り作業量の見積もりです。既定値は 0 です。

戻り値

戻り値として考えられるコードには、次の表に示す値が含まれますが、これらに限定されません。

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	ポインターが無効です。

解説(Remarks)

作業量の見積もりはプロバイダーによって決定され、通常はセッションについて見積もられた残りの作業量として解釈されます。

この値は OnProgress イベントで報告されます。

vtbl 7 HRESULT BeginOrderedGroup(BYTE* pbLowerBound)

変更バッチ内で順序付きグループを開きます。このグループはアイテム ID によって順序付けられます。

pbLowerBound

BYTE*

この順序付きグループにおけるアイテム ID の下限(その値を含む)です。下限として 0 を指定するには NULL を使用します。

戻り値

戻り値として考えられるコードには、次の表に示す値が含まれますが、これらに限定されません。

リターンコード	説明
S_OK	メソッドは成功しました。
SYNC_E_INVALID_OPERATION	既にグループが開かれているか、空のグループが以前にバッチへ追加されています。
SYNC_E_CHANGE_BATCH_IS_READ_ONLY	オブジェクトが ISyncFullEnumerationChangeBatch オブジェクトであり、既にグループがバッチへ追加されています。
SYNC_E_RANGE_OUT_OF_ORDER	オブジェクトが ISyncFullEnumerationChangeBatch オブジェクトであり、pbLowerBound がバッチの作成時に使用された下限 ID より大きい値です。

解説(Remarks)

このメソッドの呼び出し後に変更バッチへ追加されたアイテム変更は、開かれているグループへ追加されます。順序付きグループへ追加するアイテム変更は、アイテム ID の昇順で追加する必要があります。

グループが開かれるまで、変更バッチへアイテム変更を追加することはできません。

vtbl 8 HRESULT EndOrderedGroup(BYTE* pbUpperBound, ISyncKnowledge* pMadeWithKnowledge)

変更バッチ内で以前に開かれた順序付きグループを閉じます。

pbUpperBound	BYTE*	in	この順序付きグループにおけるアイテム ID の上限(その値を含む)です。上限として無限大を指定するには NULL を使用します。
pMadeWithKnowledge	ISyncKnowledge*	in	このグループを作成したレプリカのナレッジです。

戻り値

戻り値として考えられるコードには、次の表に示す値が含まれますが、これらに限定されません。

リターンコード	説明
S_OK	メソッドは成功しました。
SYNC_E_INVALID_OPERATION	グループが開かれていないか、順序なしグループが開かれています。
SYNC_E_RANGE_OUT_OF_ORDER	pbUpperBound が、グループに最後に追加されたアイテムの ID より小さい値です。
SYNC_E_CHANGE_BATCH_IS_READ_ONLY	オブジェクトが ISyncFullEnumerationChangeBatch オブジェクトであり、既にグループがバッチへ追加されています。

vtbl 9 HRESULT AddItemMetadataToGroup(BYTE* pbOwnerReplicaId, BYTE* pbItemId, SYNC_VERSION* pChangeVersion, SYNC_VERSION* pCreationVersion, DWORD dwFlags, DWORD dwWorkForChange, ISyncChangeBuilder** ppChangeBuilder)

指定されたアイテム変更を、現在開かれているグループへ追加します。

pbOwnerReplicaId	BYTE*	in	pChangeVersion と pCreationVersion が有効となるレプリカのレプリカ ID です。ID の形式は、プロバイダーの ID_PARAMETERS 構造体で指定された形式と一致している必要があります。
pbItemId	BYTE*	in	アイテムの ID です。ID の形式は、プロバイダーの ID_PARAMETERS 構造体で指定された形式と一致している必要があります。
pChangeVersion	SYNC_VERSION*	in	この変更のバージョンです。
pCreationVersion	SYNC_VERSION*	in	アイテムの作成バージョンです。
dwFlags	DWORD	in	アイテム変更の状態を指定するフラグです。フラグの値については、ISyncChange::GetFlags を参照してください。
dwWorkForChange	DWORD	in	この変更の作業量の見積もりです。この値は、変更の適用中に完了した作業量をアプリケーションへ報告するために使用されます。
ppChangeBuilder	ISyncChangeBuilder**	out	変更に対して変更単位の情報を追加するために使用できるオブジェクトを返します。

戻り値

戻り値として考えられるコードには、次の表に示す値が含まれますが、これらに限定されません。

リターンコード	説明
S_OK	メソッドは成功しました。
E_INVALIDARG	dwFlags に無効なフラグ値が含まれています。
SYNC_E_INVALID_OPERATION	グループが開かれていないか、空のグループが以前にバッチへ追加されています。
SYNC_E_RANGE_OUT_OF_ORDER	順序付きグループが開かれており、pbItemId が、そのグループに直前に追加されたアイテムのアイテム ID より小さいか、またはグループを開いたときに指定されたアイテム ID より小さい値です。
SYNC_E_CHANGE_BATCH_IS_READ_ONLY	ISyncChangeBatchBase オブジェクトが、変更アプライヤーまたは同期セッションへ既に送信されています。

vtbl 10 HRESULT GetLearnedKnowledge(ISyncKnowledge** ppLearnedKnowledge)

この変更バッチ内のすべての変更を宛先プロバイダーが適用したときに、宛先レプリカが学習するナレッジを取得します。

ppLearnedKnowledge

ISyncKnowledge**

out

この変更バッチ内のすべての変更をプロバイダーがレプリカへ適用したときに、そのレプリカが学習するナレッジを返します。このナレッジは、レプリカの現在のナレッジが変更バッチの前提ナレッジを含んでいる場合にのみ有効です。前提ナレッジは ISyncChangeBatchBase::GetPrerequisiteKnowledge を呼び出すことで取得できます。

戻り値

戻り値として考えられるコードには、次の表に示す値が含まれますが、これらに限定されません。

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	ポインターが無効です。
SYNC_E_INVALID_OPERATION	バッチに最後に追加されたグループが終了されていません。

解説(Remarks)

GetLearnedKnowledge は、カスタムの変更アプライヤーを使用するプロバイダーで利用できます。

vtbl 11 HRESULT GetPrerequisiteKnowledge(ISyncKnowledge** ppPrerequisteKnowledge)

この変更バッチを処理するために宛先プロバイダーが備えている必要のある、最小限のナレッジを取得します。

ppPrerequisteKnowledge

ISyncKnowledge**

out

この変更バッチを処理するために宛先プロバイダーが備えている必要のある、最小限のナレッジを返します。

戻り値

戻り値として考えられるコードには、次の表に示す値が含まれますが、これらに限定されません。

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	ポインターが無効です。

vtbl 12 HRESULT GetSourceForgottenKnowledge(IForgottenKnowledge** ppSourceForgottenKnowledge)

ソースレプリカの忘却ナレッジを取得します。

ppSourceForgottenKnowledge

IForgottenKnowledge**

out

ソースレプリカの忘却ナレッジを返します。

戻り値

戻り値として考えられるコードには、次の表に示す値が含まれますが、これらに限定されません。

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	ポインターが無効です。

vtbl 13 HRESULT SetLastBatch()

同期セッションで列挙する変更がこれ以上存在しないことを示すフラグを設定します。

戻り値

戻り値として考えられるコードには、次の表に示す値が含まれますが、これらに限定されません。

リターンコード	説明
S_OK	メソッドは成功しました。

解説(Remarks)

IKnowledgeSyncProvider::GetChangeBatch メソッドに応答して変更バッチを返す際、その変更バッチが最後の変更バッチである場合、ソースプロバイダーは SetLastBatch を呼び出す必要があります。

vtbl 14 HRESULT SetWorkEstimateForBatch(DWORD dwWorkForBatch)

バッチの作業量の見積もりを設定します。

dwWorkForBatch

DWORD

バッチの作業量の見積もりです。

戻り値

戻り値として考えられるコードには、次の表に示す値が含まれますが、これらに限定されません。

リターンコード	説明
S_OK	メソッドは成功しました。

解説(Remarks)

この値は OnProgress イベントで報告されます。

vtbl 15 HRESULT SetRemainingWorkEstimateForSession(DWORD dwRemainingWorkForSession)

セッションの残り作業量の見積もりを設定します。

dwRemainingWorkForSession

DWORD

セッションの残り作業量の見積もりです。

戻り値

戻り値として考えられるコードには、次の表に示す値が含まれますが、これらに限定されません。

リターンコード	説明
S_OK	メソッドは成功しました。

解説(Remarks)

作業量の見積もりはプロバイダーによって決定されます。

この値は OnProgress イベントで報告されます。この値を 0 に設定した場合、OnProgress イベントはセッション中に適用される変更ごとに発生し、完了した作業量と総作業量として 0 が渡されます。

vtbl 16 HRESULT Serialize(BYTE* pbChangeBatch, DWORD* pcbChangeBatch)

変更バッチをバイト配列へシリアル化します。

pbChangeBatch	BYTE*	inout	変更バッチのデータを受け取るバイト配列です。
pcbChangeBatch	DWORD*	inout	pbChangeBatch のバイト数を指定します。pbChangeBatch が小さすぎる場合は pbChangeBatch に必要なバイト数を返し、データが書き込まれた場合は pbChangeBatch へ書き込まれたバイト数を返します。

戻り値

戻り値として考えられるコードには、次の表に示す値が含まれますが、これらに限定されません。

リターンコード	説明
S_OK	メソッドは成功しました。
E_POINTER	ポインターが無効です。
E_OUTOFMEMORY
HRESULT_FROM_WIN32(ERROR_MORE_DATA)	pbChangeBatch が小さすぎます。この場合、必要なバイト数が pcbChangeBatch に格納されます。
SYNC_E_INVALID_OPERATION	バッチに最後に追加されたグループが終了されていません。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ISyncChangeBatchBase "{52F6E694-6A71-4494-A184-A8311BF5D227}"
#usecom global ISyncChangeBatchBase IID_ISyncChangeBatchBase "{}"
#comfunc global ISyncChangeBatchBase_GetChangeEnumerator                 3 sptr
#comfunc global ISyncChangeBatchBase_GetIsLastBatch                      4 var
#comfunc global ISyncChangeBatchBase_GetWorkEstimateForBatch             5 var
#comfunc global ISyncChangeBatchBase_GetRemainingWorkEstimateForSession  6 var
#comfunc global ISyncChangeBatchBase_BeginOrderedGroup                   7 var
#comfunc global ISyncChangeBatchBase_EndOrderedGroup                     8 var,sptr
#comfunc global ISyncChangeBatchBase_AddItemMetadataToGroup              9 var,var,var,var,int,int,sptr
#comfunc global ISyncChangeBatchBase_GetLearnedKnowledge                 10 sptr
#comfunc global ISyncChangeBatchBase_GetPrerequisiteKnowledge            11 sptr
#comfunc global ISyncChangeBatchBase_GetSourceForgottenKnowledge         12 sptr
#comfunc global ISyncChangeBatchBase_SetLastBatch                        13
#comfunc global ISyncChangeBatchBase_SetWorkEstimateForBatch             14 int
#comfunc global ISyncChangeBatchBase_SetRemainingWorkEstimateForSession  15 int
#comfunc global ISyncChangeBatchBase_Serialize                           16 var,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_ISyncChangeBatchBase "{52F6E694-6A71-4494-A184-A8311BF5D227}"
#usecom global ISyncChangeBatchBase IID_ISyncChangeBatchBase "{}"
#comfunc global ISyncChangeBatchBase_GetChangeEnumerator                 3 sptr
#comfunc global ISyncChangeBatchBase_GetIsLastBatch                      4 sptr
#comfunc global ISyncChangeBatchBase_GetWorkEstimateForBatch             5 sptr
#comfunc global ISyncChangeBatchBase_GetRemainingWorkEstimateForSession  6 sptr
#comfunc global ISyncChangeBatchBase_BeginOrderedGroup                   7 sptr
#comfunc global ISyncChangeBatchBase_EndOrderedGroup                     8 sptr,sptr
#comfunc global ISyncChangeBatchBase_AddItemMetadataToGroup              9 sptr,sptr,sptr,sptr,int,int,sptr
#comfunc global ISyncChangeBatchBase_GetLearnedKnowledge                 10 sptr
#comfunc global ISyncChangeBatchBase_GetPrerequisiteKnowledge            11 sptr
#comfunc global ISyncChangeBatchBase_GetSourceForgottenKnowledge         12 sptr
#comfunc global ISyncChangeBatchBase_SetLastBatch                        13
#comfunc global ISyncChangeBatchBase_SetWorkEstimateForBatch             14 int
#comfunc global ISyncChangeBatchBase_SetRemainingWorkEstimateForSession  15 int
#comfunc global ISyncChangeBatchBase_Serialize                           16 sptr,sptr
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。