Win32 API 日本語リファレンス
ホーム › UI.Shell › ISyncMgrSynchronize

ISyncMgrSynchronize

COM
📘 Microsoft Learn (日本語) · English
IID6295df40-35ee-11d1-8707-00c04fd93327継承元IUnknown自前メソッド開始 vtbl3

公式ドキュメント

登録されたアプリケーションまたはサービスが同期マネージャーから通知を受け取ることを可能にするメソッドを公開します。

解説(Remarks)

実装するタイミング

このインターフェイスは、同期マネージャーから通知を受け取り、同期プロセスに参加するために、登録されたアプリケーションのハンドラーに実装する必要があります。

ISyncMgrSynchronize は、Windows Vista で ISyncMgrHandler に置き換えられました。

使用するタイミング

同期マネージャーは、同期中に登録されたアプリケーションまたはサービスへ通知を送信するために、このインターフェイスのメソッドを呼び出します。

メソッド 10

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

vtbl 3 HRESULT Initialize(DWORD dwReserved, DWORD dwSyncMgrFlags, DWORD cbCookie, BYTE* lpCookie)

登録されたアプリケーションのハンドラーが同期イベントを処理するかどうかを判断するために、同期マネージャーによって呼び出されます。

dwReservedDWORDin予約済み。0 (ゼロ) を指定する必要があります。
dwSyncMgrFlagsDWORDin同期イベントの開始方法を示す SYNCMGRFLAG 列挙値です。
cbCookieDWORDinlpCookie データのサイズ (バイト単位) です。
lpCookieBYTE*inアプリケーションを識別するトークンへのポインターです。このトークンは、アプリケーションが同期マネージャーをプログラムで呼び出すときに渡されます。

戻り値

型: HRESULT

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

戻り値 説明
S_OK
 初期化に成功しました。
S_FALSE
 アプリケーションハンドラーは同期イベントを処理しません。

解説(Remarks)

SYNCMGRFLAG 列挙値は ISyncMgrSynchronize インターフェイスの存続期間を通じて適用され、他の ISyncMgrSynchronize メソッドによって使用されます。

アプリケーションが SYNCMGRFLAG イベントを認識しない場合、アプリケーションはそのイベントを手動同期として扱う必要があります。

登録されたアプリケーションハンドラーは、初期化メソッドが初めて呼び出される場合を除き、この呼び出し内でユーザーインターフェイスを表示できません。アプリケーションは、項目のセットアップやアプリケーション機能のユーザーへの紹介に必要な一度限りの初期化を表示できます。同期プロセスの一部として別の理由でユーザーインターフェイスを表示する必要がある場合は、ISyncMgrSynchronize::PrepareForSync メソッドを使用できます。

処理を行うアプリケーションが UpdateItems を使用して同期マネージャーをプログラムで呼び出さない限り、lpCookie パラメーターは NULL です。このシナリオでは、クラス識別子 (CLSID) が処理を行うアプリケーションを識別し、lpCookie の値は処理を行うアプリケーションによって渡され、その後、同期時にコンテキストとして同期マネージャーによって返されます。lpCookie パラメーターは、SYNCMGRFLAG_INVOKE が設定されている場合にのみ意味を持ちます。

vtbl 4 HRESULT GetHandlerInfo(SYNCMGRHANDLERINFO** ppSyncMgrHandlerInfo)

ハンドラー情報を取得します。

ppSyncMgrHandlerInfoSYNCMGRHANDLERINFO**outSYNCMGRHANDLERINFO 構造体へのポインターです。

戻り値

型: HRESULT

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

戻り値 説明
S_OK
 ハンドラー情報が正常に返されました。

解説(Remarks)

ハンドラーは、メモリを割り当てるために CoTaskMemAlloc 関数を使用する必要があります。

vtbl 5 HRESULT EnumSyncMgrItems(ISyncMgrEnumItems** ppSyncMgrEnumItems)

登録されたアプリケーションによって処理される項目に対する ISyncMgrEnumItems インターフェイスを取得します。

ppSyncMgrEnumItemsISyncMgrEnumItems**out有効な ISyncMgrEnumItems インターフェイスへのポインターを受け取る変数のアドレスです。

戻り値

型: HRESULT

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

戻り値 説明
S_OK
 列挙インターフェイスが正常に返されました。
S_SYNCMGR_MISSINGITEMS
 列挙インターフェイスオブジェクトは正常に返されましたが、一部の項目が欠落しています。この成功コードが返された場合、同期マネージャーは、列挙子で返されなかった ItemId に対して保存された設定を削除しません。

解説(Remarks)

このメソッドが作成する列挙オブジェクトは ISyncMgrEnumItems インターフェイスを実装します。これは、Next、Reset、Clone、Skip メソッドを含む標準的な列挙インターフェイスです。

vtbl 6 HRESULT GetItemObject(GUID* ItemID, GUID* riid, void** ppv)

登録されたアプリケーションが処理する指定された項目に対するインターフェイスを取得します。

ItemIDGUID*in要求された項目の識別子です。
riidGUID*in要求されたインターフェイスの識別子です。
ppvvoid**out要求されたインターフェイスへのポインターを受け取る変数のアドレスです。

戻り値

型: HRESULT

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

戻り値 説明
E_NOTIMPL
 要求されたインターフェイスが見つかりません。

解説(Remarks)

このメソッドは将来の互換性のためにのみ存在します。現在、項目に対して定義されているインターフェイスはありません。アプリケーションの実装者は、このメソッドから E_NOTIMPL を返す必要があります。

vtbl 7 HRESULT ShowProperties(HWND hWndParent, GUID* ItemID)

ユーザーが選択ダイアログボックスで項目を選択し、[プロパティ] ボタンをクリックしたときに、同期マネージャーによって呼び出されます。

hWndParentHWNDin登録されたアプリケーションがプロパティを設定するために表示するユーザーインターフェイスの親 HWND です。この値は NULL にできます。
ItemIDGUID*inプロパティが要求される項目の ID です。

戻り値

型: HRESULT

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

戻り値 説明
S_OK
 項目のプロパティダイアログが正常に処理されました。

解説(Remarks)

登録されたアプリケーションが項目のプロパティダイアログボックスを提供する場合は、SYNCMGRITEM 構造体の dwFlags メンバーに SYNCMGRITEM_HASPROPERTIES ビットを設定する必要があります。

ItemID が GUID_NULL の場合、ハンドラーはハンドラー全体のプロパティダイアログを表示する必要があります。

表示されるダイアログボックスの外観は、標準的なプロパティページのダイアログボックスと一貫している必要があります。

vtbl 8 HRESULT SetProgressCallback(ISyncMgrSynchronizeCallback* lpCallBack)

ISyncMgrSynchronizeCallback インターフェイスを設定します。登録されたアプリケーションは、このコールバックインターフェイスを使用して、ISyncMgrSynchronize::PrepareForSync および ISyncMgrSynchronize::Synchronize メソッド内から状態情報を提供します。

lpCallBackISyncMgrSynchronizeCallback*in登録されたアプリケーションが同期状態について SyncMgr へフィードバックを提供し、同期が完了したときに SyncMgr へ通知するために使用する ISyncMgrSynchronizeCallback インターフェイスへのポインターです。

戻り値

型: HRESULT

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

戻り値 説明
S_OK
 同期コールバックインターフェイスが正常に設定されました。

解説(Remarks)

登録されたアプリケーションは、ISyncMgrSynchronizeCallback::AddRef メソッドを呼び出し、状態テキストや進行状況インジケーターのフィードバックを提供するために SyncMgr を呼び出すときにそれを使用する必要があります。

メソッドが呼び出されたときに登録されたアプリケーションが既に ISyncMgrSynchronizeCallback インターフェイスを保持している場合は、古いインターフェイスを解放し、新しいインターフェイスの AddRef メソッドを呼び出す必要があります。新しいインターフェイスは、登録されたアプリケーションによって保持されなければなりません。

ISyncMgrSynchronize インターフェイスが解放される前に、SyncMgr は pSyncCallBack パラメーターを NULL に設定してこのメソッドを呼び出します。その後、登録されたアプリケーションは、以前に渡された ISyncMgrSynchronize インターフェイスを解放する必要があります。

vtbl 9 HRESULT PrepareForSync(DWORD cbNumItems, GUID* pItemIDs, HWND hWndParent, DWORD dwReserved)

登録されたアプリケーションが、ISyncMgrSynchronize::Synchronize メソッドが呼び出される前に、任意のユーザーインターフェイスを表示し、必要な初期化を実行できるようにします。

cbNumItemsDWORDinpItemIDs が指す配列内の項目数です。
pItemIDsGUID*inユーザーが同期対象として選択した項目 ID の配列です。
hWndParentHWNDin登録されたアプリケーションが表示するユーザーインターフェイス要素に使用すべき親 HWND へのハンドルです。この値は NULL の場合があります。
dwReservedDWORDin予約済み。登録されたアプリケーションはこの値を無視する必要があります。

戻り値

型: HRESULT

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

戻り値 説明
S_OK
 準備に成功しました。

解説(Remarks)

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

登録されたアプリケーションは、ISyncMgrSynchronize::Initialize メソッドの dwSyncFlags パラメーターに SYNCMGRFLAG_MAYBOTHERUSER フラグが設定されている場合にのみ、ユーザーインターフェイスを表示する必要があります。SYNCMGRFLAG_MAYBOTHERUSER フラグが設定されていないときに、ユーザーインターフェイスを表示せずに同期の準備ができない場合、登録されたアプリケーションはこのメソッドから S_FALSE を返す必要があります。

このメソッドに渡される項目 ID の配列は、ISyncMgrSynchronize::Synchronize メソッドにも関連します。

ISyncMgrSynchronizeCallback メソッドは、登録されたアプリケーション内の任意のスレッドで呼び出すことができます。

vtbl 10 HRESULT Synchronize(HWND hWndParent)

ユーザーが同期対象の登録されたアプリケーションを選択した後、選択された各グループについて 1 回ずつ、同期マネージャーによって呼び出されます。

hWndParentHWNDin登録されたアプリケーションが表示するユーザーインターフェイス要素に使用すべき親 HWND へのハンドルです。この値は NULL の場合があります。

戻り値

型: HRESULT

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

戻り値 説明
S_OK
 同期に成功しました。
E_FAIL
 同期に失敗しました。

解説(Remarks)

ユーザーが登録されたアプリケーションに対して項目の選択を一切行わなかった場合、ISyncMgrSynchronize::Synchronize メソッドは呼び出されず、インターフェイスは解放されます。このメソッドが呼び出された場合、アプリケーションは ISyncMgrSynchronize::PrepareForSync メソッドで指定された項目を同期する必要があります。

登録されたアプリケーションのハンドラーは、ISyncMgrSynchronize::Synchronize メソッドからできるだけ早く戻り、その後 SynchronizeCompleted メソッドを呼び出す必要があります。ハンドラーが ISyncMgrSynchronize::Synchronize メソッドから戻る前に SynchronizeCompleted の呼び出しを行うことも許容されます。

アプリケーションは、ISyncMgrSynchronize::SetProgressCallback メソッドで設定された pSyncCallBack インターフェイスポインターを使用して、進行状況のフィードバックを提供し、同期をキャンセルすべきかどうかを確認する必要があります。

アプリケーションは、ISyncMgrSynchronize::Initialize で SYNCMGRFLAG_MAYBOTHERUSER フラグが指定されていない場合でも、進行状況情報を提供する必要があります。

アプリケーションは、ISyncMgrSynchronize::Synchronize メソッド内からユーザーインターフェイス要素を表示しないようにする必要があります。ユーザーインターフェイス要素は ISyncMgrSynchronize::PrepareForSync および ISyncMgrSynchronize::ShowError メソッドで表示することで、エンドユーザーは、ログオンと同期対象の共有の指定に限定された一貫したユーザーインターフェイスを体験できます。その後、同期はユーザーの介入なしに実行できます。同期が完了した後、競合やその他のエラーメッセージを表示できます。

ISyncMgrSynchronizeCallback メソッドは、アプリケーション内の任意のスレッドで呼び出すことができます。

vtbl 11 HRESULT SetItemStatus(GUID* pItemID, DWORD dwSyncMgrStatus)

次の 2 つのケースにおいて項目の状態を変更するために、登録されたアプリケーションのハンドラー内で同期マネージャーによって呼び出されます。すなわち、ハンドラーが ISyncMgrSynchronize::PrepareForSync メソッドから戻ってから PrepareForSyncCompleted コールバックメソッドを呼び出すまでの間、またはハンドラーが ISyncMgrSynchronize::Synchronize メソッドから戻ったがまだ SynchronizeCompleted コールバックメソッドを呼び出していない間です。

pItemIDGUID*in状態が変更された項目を識別します。
dwSyncMgrStatusDWORDinSYNCMGRSTATUS 列挙から取得した、指定された項目の新しい状態です。

戻り値

型: HRESULT

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

戻り値 説明
S_OK
 状態が設定されました。

解説(Remarks)

現在、SyncMgr がサポートする SYNCMGRSTATUS 状態値は SYNCMGRSTATUS_SKIPPED のみです。登録されたアプリケーションのハンドラーは、この状態値を受け取ったときに、pItemID で指定された項目をスキップする必要があります。

vtbl 12 HRESULT ShowError(HWND hWndParent, GUID* ErrorID)

ユーザーがエラータブ内の関連メッセージをダブルクリックしたときに、登録されたアプリケーションのハンドラー内で同期マネージャーによって呼び出されます。

hWndParentHWNDin登録されたアプリケーションがユーザーインターフェイスを表示するために使用すべき親 HWND へのハンドルです。この値は NULL にできます。
ErrorIDGUID*inこのエラーメッセージに関連付けられたエラー識別子です。この値は LogError メソッドで渡されます。

戻り値

型: HRESULT

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

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

解説(Remarks)

ハンドラーは、このメソッドからできるだけ早く戻り、ShowErrorCompleted メソッドを呼び出す必要があります。ハンドラーは、このメソッドから戻る前に ShowErrorCompleted を呼び出すことができます。ハンドラーがこのメソッドから失敗コードを返す場合は、 ShowErrorCompleted メソッドを呼び出さないでください。

アプリケーションは、ISyncMgrSynchronize::Initialize メソッドの dwSyncFlags パラメーターに SYNCMGRFLAG_MAYBOTHERUSER フラグが設定されていない場合でも、このメソッドでユーザーインターフェイス要素を表示できます。ただし、アプリケーションは、ユーザーインターフェイスを表示する前に、依然として EnableModeless を呼び出し、戻りコードを確認する必要があります。

出典・ライセンス: 上記「公式ドキュメント」の内容は 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_ISyncMgrSynchronize "{6295DF40-35EE-11D1-8707-00C04FD93327}"
#usecom global ISyncMgrSynchronize IID_ISyncMgrSynchronize "{}"
#comfunc global ISyncMgrSynchronize_Initialize           3 int,int,int,var
#comfunc global ISyncMgrSynchronize_GetHandlerInfo       4 var
#comfunc global ISyncMgrSynchronize_EnumSyncMgrItems     5 sptr
#comfunc global ISyncMgrSynchronize_GetItemObject        6 var,var,sptr
#comfunc global ISyncMgrSynchronize_ShowProperties       7 sptr,var
#comfunc global ISyncMgrSynchronize_SetProgressCallback  8 sptr
#comfunc global ISyncMgrSynchronize_PrepareForSync       9 int,var,sptr,int
#comfunc global ISyncMgrSynchronize_Synchronize          10 sptr
#comfunc global ISyncMgrSynchronize_SetItemStatus        11 var,int
#comfunc global ISyncMgrSynchronize_ShowError            12 sptr,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。