ホーム › UI.Shell › ISyncMgrSynchronizeCallback

ISyncMgrSynchronizeCallback

COM

📘 Microsoft Learn (日本語) · English

IID6295df41-35ee-11d1-8707-00c04fd93327継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

同期プロセスを管理するメソッドを公開します。

解説(Remarks)

実装するタイミング

このインターフェイスは、同期プロセス中にステータス、エラー、進行状況の情報を受け取り、ユーザーインターフェイスを表示するために、同期マネージャーによって実装されます。

使用するタイミング

アプリケーションは、このインターフェイスのメソッドをできるだけ頻繁に呼び出す必要があり、また、個々の項目がユーザーによってキャンセルされたかどうかを確認するために、新しい各 ItemID を開始する前に必ず呼び出す必要があります。

メソッド 9

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

vtbl 3 HRESULT ShowPropertiesCompleted(HRESULT hr)

登録されたアプリケーションのハンドラーが、その ShowProperties 操作の完了前または完了後に呼び出します。

HRESULT

ShowProperties が成功したかどうか。

戻り値

型: HRESULT

このメソッドは次の値のいずれかを返すことができます。

戻り値コード	説明
S_OK	呼び出しが正常に完了しました。

解説(Remarks)

登録されたアプリケーションのハンドラーが、ShowProperties メソッドから戻る前にこのメソッドを呼び出しても問題ありません。

登録されたアプリケーションのハンドラーが ShowProperties メソッドから成功コードを返さない場合は、このメソッドを呼び出さないでください。

vtbl 4 HRESULT PrepareForSyncCompleted(HRESULT hr)

アプリケーションの登録されたハンドラーが、PrepareForSync メソッドの完了後に呼び出します。

HRESULT

PrepareForSync メソッドの戻り値。S_OK が返された場合、同期マネージャーはその項目に対して Synchronize を呼び出します。HRESULT が S_OK 以外の値に設定されている場合、同期マネージャーは Synchronize メソッドを呼び出さずにハンドラーを解放します。

戻り値

型: HRESULT

このメソッドは次の値のいずれかを返すことができます。

戻り値コード	説明
S_OK	呼び出しが正常に完了しました。

解説(Remarks)

アプリケーションの登録されたハンドラーは、 PrepareForSync メソッドからできるだけ早く戻り、その後このメソッドを呼び出して、登録されたアプリケーションが同期の準備を行っていることを同期マネージャーに通知する必要があります。

アプリケーションの登録されたハンドラーが、PrepareForSync メソッドから戻る前にこのメソッドを呼び出しても問題ありません。

アプリケーションの登録されたハンドラーは、 PrepareForSync メソッドが S_OK 以外の値を返す場合は、このメソッドを呼び出さないでください。

vtbl 5 HRESULT SynchronizeCompleted(HRESULT hr)

アプリケーションが、その Synchronize メソッドの完了時に呼び出します。

HRESULT

Synchronize メソッドから返された結果。

戻り値

型: HRESULT

このメソッドは次の値のいずれかを返すことができます。

戻り値コード	説明
S_OK	呼び出しが正常に完了しました。

解説(Remarks)

アプリケーションの登録されたハンドラーは、 Synchronize メソッドからできるだけ早く戻り、その後このメソッドを呼び出して、同期プロセスが完了したことを同期マネージャーに通知する必要があります。

アプリケーションの登録されたハンドラーが、Synchronize メソッドから戻る前にこのメソッドを呼び出しても問題ありません。

ただし、アプリケーションの登録されたハンドラーは、Synchronize メソッドが S_OK 以外の値を返す場合は、このメソッドを呼び出さないでください。

vtbl 6 HRESULT ShowErrorCompleted(HRESULT hr, DWORD cItems, GUID* pItemIDs)

登録されたアプリケーションのハンドラーが、その PrepareForSync 操作の完了前または完了後に呼び出します。

hr	HRESULT	in	ShowError が成功したかどうか。登録されたアプリケーションのハンドラーが SyncMgr に同期の再試行を要求する場合、この値は S_SYNCMGR_RETRYSYNC になります。この値が SyncMgr に返されると、 PrepareForSync メソッドと Synchronize メソッドの両方が再度呼び出されます。
cItems	DWORD	in	pItemIDs パラメーターが指す配列内の項目数。このパラメーターは、hrResult が S_SYNCMGR_RETRYSYNC でない限り無視されます。
pItemIDs	GUID*	in	再試行時に PrepareForSync に渡す項目 ID の配列へのポインター。このパラメーターは、hrResult が S_SYNCMGR_RETRYSYNC でない限り無視されます。

戻り値

型: HRESULT

このメソッドは次の値のいずれかを返すことができます。

戻り値コード	説明
S_OK	操作が正常に完了しました。

解説(Remarks)

pItemIDs パラメーターは [in] パラメーターであり、呼び出し側の関数がそれが指すメモリを所有します。SyncMgr は戻る前に配列のコピーを作成します。

登録されたアプリケーションのハンドラーは、ShowError メソッドからできるだけ早く戻り、その後このメソッドを呼び出して、ShowError の呼び出しの処理が完了したことを SyncMgr に通知する必要があります。

登録されたアプリケーションのハンドラーが、ShowError メソッドから戻る前にこのメソッドを呼び出しても問題ありません。

登録されたアプリケーションのハンドラーは、ShowError メソッドから成功コードが返されない限り、このメソッドを呼び出さないでください。

vtbl 7 HRESULT EnableModeless(BOOL fEnable)

登録されたアプリケーションが、PrepareForSync および Synchronize メソッド内からダイアログボックスを表示する前後に呼び出します。

fEnable

BOOL

登録されたアプリケーションがダイアログボックスの表示許可を要求している場合は TRUE、登録されたアプリケーションがダイアログボックスの表示を完了した場合は FALSE。

戻り値

型: HRESULT

このメソッドは次の値のいずれかを返すことができます。

戻り値コード	説明
S_OK	同期を続行します。
S_FALSE	ダイアログボックスを表示しないでください。

解説(Remarks)

ダイアログボックスの表示許可を要求するには、登録されたアプリケーションはまず fEnable を TRUE に設定して ISyncMgrSynchronizeCallback::EnableModeless を呼び出します。S_OK が返された場合、登録されたアプリケーションはダイアログボックスを表示できます。ダイアログボックスの表示が完了したら、登録されたアプリケーションは fEnable を FALSE に設定して ISyncMgrSynchronizeCallback::EnableModeless を呼び出し、他の項目がユーザーインターフェイス要素を表示できるようになったことを SyncMgr に通知する必要があります。

vtbl 8 HRESULT Progress(GUID* ItemID, SYNCMGRPROGRESSITEM* pSyncProgressItem)

登録されたアプリケーションが、進行状況情報を更新し、操作を続行すべきかどうかを判断するために呼び出します。

ItemID	GUID*	in	更新中の項目の項目識別子への参照。
pSyncProgressItem	SYNCMGRPROGRESSITEM*	in	更新された進行状況情報を含む SYNCMGRPROGRESSITEM 構造体へのポインター。

戻り値

型: HRESULT

このメソッドは次の値のいずれかを返すことができます。

戻り値コード	説明
S_OK	同期を続行します。
S_SYNCMGR_CANCELITEM	指定された項目の同期をできるだけ早くキャンセルします。
S_SYNCMGR_CANCELALL	このアプリケーションに関連付けられているすべての項目の同期をできるだけ早くキャンセルします。

解説(Remarks)

登録されたアプリケーションは、SYNCMGRFLAG_MAYBOTHERUSER フラグが設定されている場合でも、通常のフィードバックを提供するためにこのメソッドを呼び出す必要があります。

vtbl 9 HRESULT LogError(DWORD dwErrorLevel, LPWSTR pszErrorText, SYNCMGRLOGERRORINFO* pSyncLogError)

登録されたアプリケーションが、同期マネージャーのステータスダイアログボックスのエラータブに情報、警告、またはエラーメッセージを記録するために呼び出します。

dwErrorLevel	DWORD	in	エラーレベル。値は SYNCMGRLOGLEVEL 列挙体から取得されます。
pszErrorText	LPWSTR	in	エラータブに表示するエラーテキストへのポインター。
pSyncLogError	SYNCMGRLOGERRORINFO*	in	追加のエラー情報を含む SYNCMGRLOGERRORINFO 構造体へのポインター。このデータを提供しない登録済みアプリケーションは NULL を渡すことができます。

戻り値

型: HRESULT

このメソッドは、標準の戻り値 E_INVALIDARG、E_UNEXPECTED、E_OUTOFMEMORY、および次の値をサポートします。

戻り値コード	説明
S_OK	エラー情報が正常に記録されました。

vtbl 10 HRESULT DeleteLogError(GUID* ErrorID, DWORD dwReserved)

登録されたアプリケーションのハンドラーが、同期マネージャーのステータスダイアログボックスのエラータブに以前記録した ErrorInformation、警告、またはエラーメッセージを削除するために呼び出します。

ErrorID	GUID*	in	削除する LogError。ErrorID が GUID_NULL の場合、登録されたアプリケーションのハンドラーのインスタンスによって記録されたすべてのエラーが削除されます。
dwReserved	DWORD	in

戻り値

型: HRESULT

このメソッドは、標準の戻り値 E_INVALIDARG、E_UNEXPECTED、E_OUTOFMEMORY、および次の値をサポートします。

戻り値コード	説明
S_OK	項目がログから正常に削除されました。

vtbl 11 HRESULT EstablishConnection(LPWSTR pwszConnection, DWORD dwReserved)

登録されたアプリケーションのハンドラーが、ネットワーク接続が必要な場合に呼び出します。

pwszConnection	LPWSTR	in	ダイヤルする接続の名前。
dwReserved	DWORD	in

戻り値

型: HRESULT

このメソッドは、標準の戻り値 E_INVALIDARG、E_UNEXPECTED、E_OUTOFMEMORY、および次の値をサポートします。

戻り値コード	説明
S_OK	接続が正常に確立されました。

解説(Remarks)

pwszConnection が NULL の場合、SyncMgr は既定の自動ダイヤル接続を使用する必要があります。

ハンドラーによって EstablishConnection のインスタンスが呼び出されると、SyncMgr は接続の確立を試みます。その後に別の EstablishConnection が呼び出された場合、SyncMgr は以前の接続を応答不能にすることなく、新しい接続を試みます。すべての接続は、すべてのハンドラーが同期を完了するまで維持されます。すべてのハンドラーが同期を完了した後、開かれていた接続はすべて SyncMgr によって閉じられます。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ISyncMgrSynchronizeCallback "{6295DF41-35EE-11D1-8707-00C04FD93327}"
#usecom global ISyncMgrSynchronizeCallback IID_ISyncMgrSynchronizeCallback "{}"
#comfunc global ISyncMgrSynchronizeCallback_ShowPropertiesCompleted  3 int
#comfunc global ISyncMgrSynchronizeCallback_PrepareForSyncCompleted  4 int
#comfunc global ISyncMgrSynchronizeCallback_SynchronizeCompleted     5 int
#comfunc global ISyncMgrSynchronizeCallback_ShowErrorCompleted       6 int,int,var
#comfunc global ISyncMgrSynchronizeCallback_EnableModeless           7 int
#comfunc global ISyncMgrSynchronizeCallback_Progress                 8 var,var
#comfunc global ISyncMgrSynchronizeCallback_LogError                 9 int,wstr,var
#comfunc global ISyncMgrSynchronizeCallback_DeleteLogError           10 var,int
#comfunc global ISyncMgrSynchronizeCallback_EstablishConnection      11 wstr,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_ISyncMgrSynchronizeCallback "{6295DF41-35EE-11D1-8707-00C04FD93327}"
#usecom global ISyncMgrSynchronizeCallback IID_ISyncMgrSynchronizeCallback "{}"
#comfunc global ISyncMgrSynchronizeCallback_ShowPropertiesCompleted  3 int
#comfunc global ISyncMgrSynchronizeCallback_PrepareForSyncCompleted  4 int
#comfunc global ISyncMgrSynchronizeCallback_SynchronizeCompleted     5 int
#comfunc global ISyncMgrSynchronizeCallback_ShowErrorCompleted       6 int,int,sptr
#comfunc global ISyncMgrSynchronizeCallback_EnableModeless           7 int
#comfunc global ISyncMgrSynchronizeCallback_Progress                 8 sptr,sptr
#comfunc global ISyncMgrSynchronizeCallback_LogError                 9 int,wstr,sptr
#comfunc global ISyncMgrSynchronizeCallback_DeleteLogError           10 sptr,int
#comfunc global ISyncMgrSynchronizeCallback_EstablishConnection      11 wstr,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。