ISyncMgrHandler::Synchronize メソッド (syncmgr.h)

[アーティクル]
08/26/2023

ハンドラーの同期項目の選択の同期を開始します。

構文

HRESULT Synchronize(
  [in] LPCWSTR                *ppszItemIDs,
  [in] ULONG                  cItems,
  [in] HWND                   hwndOwner,
  [in] ISyncMgrSessionCreator *pSessionCreator,
  [in] IUnknown               *punk
);

パラメーター

[in] ppszItemIDs

種類: LPCWSTR*

同期する項目を表す項目 ID の配列へのポインター。各項目 ID は、終端の null 文字を含む最大長MAX_SYNCMGR_IDです。

[in] cItems

種類: ULONG

ppszItemIDs 内の項目の数。

[in] hwndOwner

型: HWND

必要な UI を表示するために項目が使用するウィンドウへのハンドル。この値は NULL にすることができます。

[in] pSessionCreator

種類: ISyncMgrSessionCreator*

ISyncMgrSessionCreator インターフェイスへのポインター。このインターフェイスを使用すると、ハンドラー自体が進行状況とイベントを報告したり、バックグラウンドプロセスに進行状況とイベントを報告するように通知したりできます。

[in] punk

種類: IUnknown*

ISyncMgrControl に渡されるインターフェイスへのポインター。 ISyncMgrHandler::Synchronize は、ユーザーが同期センターフォルダーから同期を要求したとき、または StartSyncAll などの ISyncMgrControl 同期メソッドの 1 つが呼び出されたときに呼び出されます。

戻り値

種類: HRESULT

このメソッドは、成功すると S_OK を返します。そうでない場合は、HRESULT エラーコードを返します。

注釈

ISyncMgrHandler::Synchronize は、独自のスレッドで呼び出されます。 Sync Center は、そのスレッドでハンドラーオブジェクトとセッション作成者オブジェクトをインスタンス化し、このメソッドを呼び出します。

ハンドラーは、 CreateSession メソッドを呼び出してセッション自体を作成することも、外部プロセスに同期を実行するように通知することもできます。ハンドラーがセッションを作成する場合は、同期が完了するまで ISyncMgrHandler::Synchronize メソッドから返さないでください。ハンドラーが同期を外部プロセスに委任する場合、外部プロセスは CoCreateInstance を使用して CLSID_SyncMgrClient オブジェクトを作成し、 ISyncMgrSessionCreator インターフェイスを指定する必要があります。その後、プロセスによってセッションが作成され、進行状況を報告できるようになります。

ユーザーは、アイテムまたはハンドラーの同期を停止することを選択できます。アプリケーションは、 ISyncMgrControl インターフェイスで StopItemSync などの停止メソッドのいずれかを呼び出すことによって、同期を停止することもできます。これらのシナリオをサポートするために、次のメカニズムが用意されています。

ReportProgress は、キャンセルが要求されたかどうかを示すパラメーターを返します。
ハンドラーは CanContinue を呼び出すことができます。

ISyncMgrHandler::Synchronize メソッドが呼び出された後にユーザーが追加の項目を同期するように求められた場合、ハンドラーは、コールバックの QueryForAdditionalItems メソッドを使用してクエリを実行することで、同じセッション内の新しい項目を同期できます。クエリ対象のアイテムを同期することを選択した場合は、 AddItemToSession を呼び出すことができます。

一部のハンドラーは、同期されるまで項目を列挙しません。ハンドラーが同期中にこのような項目を検出した場合、セッションを通じて同期センターに通知できます。たとえば、ハンドラーが同期セットに追加する項目を検出した場合、 ProposeItem を呼び出します。項目が正常に作成されると、ハンドラーは CommitItem を呼び出します。その時点で、Sync Center によってハンドラーの追跡対象となる項目の一覧に追加されます。

ISyncMgrHandler::Synchronize メソッドは、以前の PrepareForSync メソッドと Synchronize メソッドの組み合わせに似ています。以前のインターフェイスの場合、同期センターは PrepareForSync の 直後に Synchronize を呼び出しました。 ISyncMgrHandler::Synchronize メソッドは、これら 2 つのメソッドの機能を 1 回の呼び出しに提供します。

ISyncMgrHandler::Synchronize と Synchronize のもう 1 つの違いは、以前のメソッドが同期を非同期的に実行することが想定されていた点です。同期は、1 つ以上の外部スレッドで要求をキューに入れ、その後返されます。その後、すべての項目の同期が完了したら、 SynchronizeCompleted と呼び出されます。 ISyncMgrHandler::Synchronize では、インプロセス (フォアグラウンド) 同期の同期モデル、またはアウトプロセス (バックグラウンド) 同期用の非同期モデルがサポートされています。

例

次の例は、このメソッドの実装を示しています。

STDMETHODIMP CMyDeviceHandler::Synchronize(__in_ecount(cItems) LPCWSTR *ppszItemIDs,
                              __in ULONG                   cItems,
                              __in HWND                    hwndOwner,
                              __in ISyncMgrSessionCreator *pCreator,
                              __in_opt IUnknown           *punk)
{
    HRESULT hr = S_OK;

    // Create the session since we are going to perform synchronization in
    // this method.
    ISyncMgrSyncCallback *pCallback = NULL;
    
    hr = pCreator->CreateSession(_szHandlerID, ppszItemIDs, cItems,&pCallback);
    if (SUCCEEDED(hr))
    {
        for (ULONG iItem = 0; iItem < cItems; iItem++)
        {
            SYNCMGR_CANCEL_REQUEST nCancelRequest = SYNCMGR_CR_NONE;
            ULONG   uCurrentStep = 1;
            ULONG   cMaxSteps    = 50;
            LPCWSTR pszItemID    = ppszItemIDs[iItem];
            WCHAR   szProgressText[256];

            // Find the item.
            CMyDeviceSyncItem *pItem = NULL;
            
            // _FindItem is a private class function that abstracts the
            // specifics of how the handler has implemented its storage of 
            // its items. Its internal details can remain transparent as 
            // they have no bearing on this example.
            hr = _FindItem(pszItemID, &pItem);
            if (FAILED(hr))
            {
                // _ReportProgress is another private class function that loads
                // string resources so that reports can be localized rather 
                // than use hard-coded strings. Its internal details have no 
                // bearing on this example.
                _ReportProgress(pCallback, 
                                pszItemID, 
                                IDS_ITEM_NOTFOUND,
                                SYNCMGR_PS_FAILED, 
                                0, 
                                0, 
                                &nCancelRequest);

                if (nCancelRequest != SYNCMGR_CR_NONE)
                {
                    break;
                }
                continue;
            }

            // Send the initial progress report to set min and max values.
            _ReportProgress(pCallback, 
                            pszItemID, 
                            IDS_START_ITEM_SYNC,
                            SYNCMGR_PS_UPDATING, 
                            uCurrentStep, 
                            cMaxSteps,
                            &nCancelRequest);

            for (; uCurrentStep < cMaxSteps; uCurrentStep++)
            {
                if (nCancelRequest != SYNCMGR_CR_NONE)
                {
                    break;
                }

                // Report progress.
                StringCchPrintfW(szProgressText, 
                                 ARRAYSIZE(szProgressText),
                                 L"Entry %d of %d", 
                                 uCurrentStep + 1, 
                                 cMaxSteps);

                pCallback->ReportProgress(pszItemID, 
                                          szProgressText,
                                          SYNCMGR_PS_UPDATING,
                                          uCurrentStep, 
                                          cMaxSteps,
                                          &nCancelRequest);

                // The code that accomplishes the synchronization goes here.
                // This code depends entirely on the nature of the items
                // involved in the sync. 
            }

            // Send the final progress report for this item.
            if (nCancelRequest != SYNCMGR_CR_NONE);
            {
                SYNCMGR_PROGRESS_STATUS nStatus = SYNCMGR_PS_SUCCEEDED;
                if (FAILED(hr))
                {
                    nStatus = SYNCMGR_PS_FAILED;
                }
                _ReportProgress(pCallback, 
                                ppszItemIDs[iItem], 
                                IDS_ITEM_SYNC_DONE,
                                nStatus, 
                                uCurrentStep - 1, 
                                cMaxSteps, 
                                &nCancelRequest);
            }

            hr = S_OK;

            if (nCancelRequest == SYNCMGR_CR_CANCEL_ALL)
            {
                 break;
            }
        }

        pCallback->Release();
    }

    return hr;
}

要件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	syncmgr.h

ISyncMgrHandler::Synchronize メソッド (syncmgr.h)

構文

パラメーター

戻り値

注釈

例

要件

フィードバック

フィードバック

その他のリソース