ISyncMgrSyncCallback

同期処理が Sync Center に進行状況やイベントを報告したり、処理がキャンセルされたかどうかを問い合わせたりできるようにするメソッドを公開します。

このインターフェイスは ISyncMgrSessionCreator::CreateSession に渡され、それが ISyncMgrHandler::Synchronize の呼び出しの中で参照されます。

ハンドラーは、各項目についてフォルダーの進行状況 UI を更新するため、また各項目の同期が完了したときに Sync Center に通知するために、このインターフェイスを呼び出すことが期待されます。

ISyncMgrSyncCallback は ISyncMgrSynchronizeCallback の置き換えです。

単一の同期項目の同期の進行状況を Sync Center に報告します。

型: HRESULT

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

個々の同期項目ではなくハンドラーの進行状況を報告したい場合は、ISyncMgrSyncCallback::SetHandlerProgressText を呼び出します。

同期がキャンセルされた場合、ハンドラーはその項目に対して最後にもう一度 ISyncMgrSyncCallback::ReportProgress を呼び出し、nStatus パラメーターに SYNCMGR_PS_CANCELED を指定してキャンセル要求を確認します。これにより UI が更新され、ユーザーはその項目の同期を再開できるようになります。

このメソッドがいったん完了ステータス（SYNCMGR_PS_SUCCEEDED、SYNCMGR_PS_FAILED、または SYNCMGR_PS_CANCELED）を報告すると、その後に報告できるステータスは SYNCMGR_PS_FAILED のみになります。それ以外の値を指定すると、このメソッドは E_ACCESSDENIED を返し、Sync Center はその項目を失敗としてマークします。

このメソッドは Progress を置き換えます。

進行状況文字列の最大長は MAX_SYNCMGR_PROGRESSTEXT です。この定数は SyncMgr.h で定義されています。

例

次の例は、Synchronize メソッドによる ISyncMgrSyncCallback::ReportProgress の使用方法を示しています。

STDMETHODIMP CMyDeviceHandler::Synchronize(...)
{
    ...

    // Start synchronizing the sync item.

    ...

    // Construct a string to display in the Sync Center folder.
    // Report the progress to Sync Center.
    SYNCMGR_CANCEL_REQUEST nCancelRequest;
    hr = pCallback->ReportProgress(pszItemID,
                                   pszProgressText,
                                   SYNCMGR_PS_UPDATING,
                                   uCurrentStep,
                                   uMaxStep,
                                   &nCancelRequest);
    if (SUCCEEDED(hr))
    {
        if (nCancelRequest != SYNCMGR_CR_NONE)
        {
            // Synchronization was canceled.
            hr = pCallback->ReportProgress(pszItemID,
                                           pszProgressText,
                                           SYNCMGR_PS_CANCELED,
                                           uCurrentStep,
                                           uMaxStep,
                                           NULL);
        }
    }
    ...
}

ハンドラーが同期を実行している間、そのハンドラーの情報フィールドの内容を設定します。

型: HRESULT

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

同期中の項目について、Sync Results フォルダーに追加するイベントを提供します。

型: HRESULT

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

ハンドラーが同期結果に関する詳細をユーザーに提供できるように、ハンドラーが報告する個々の同期結果のプロパティシートを拡張できます。

このメソッドは LogError を置き換えます。

イベントはメモリ内にのみ格納されるため、ユーザーがログオフまたはシャットダウンすると、すべてのイベントがクリアされます。これは、カスタムの ISyncMgrEventStore を実装する理由の 1 つです。カスタム実装は、ファイル、ネットワーク経由、レジストリなど、任意の場所からイベントを提供できます。ただし、Sync Results フォルダーには、内部イベントストアと同期ハンドラーが提供するカスタムイベントストアの両方から提供されるイベントが表示されます。

例

次の例は、Synchronize メソッドによる ISyncMgrSyncCallback::ReportProgress の使用方法を示しています。

STDMETHODIMP CMyDeviceHandler::Synchronize(...)
{
    ...
    // Get the event receiver interface.
    ISyncMgrEventReceiver *pEventReceiver = NULL;
    hr = pCallback->QueryInterface(IID_ISyncMgrEventReceiver,
                                   (void **) &pEventReceiver);

    ...

    // Start synchronizing the sync item.

    ...

    // Generate a GUID for this item.
    // Construct a string to display in the Sync Results folder.
    // Store the information about this event so we can display more details.
    // Report the event to Sync Center.
    hr = pEventReceiver->ReportEvent(pszItemID,
                                     SYNCMGR_EL_INFORMATION,
                                     SYNCMGR_EF_NONE,
                                     pszEventName,
                                     pszEventDescription,
                                     NULL,
                                     NULL,
                                     NULL,
                                     &guidEventID);
    ...
}

同期がキャンセルされたかどうかを判定します。

型: HRESULT

pszItemID が NULL または空文字列の場合、戻り値はハンドラー全体に対してキャンセルが要求されているかどうかによって決まります。

同期は、コンテキストメニューまたはコマンドモジュールの 停止 または すべて停止 タスクをクリックすることでユーザーがキャンセルできます。また、アプリケーションが ISyncMgrControl インターフェイスの停止メソッドのいずれかを呼び出したときにもキャンセルできます。

この機能を独立したメソッドとして実装することで、ハンドラーは進行状況を報告することなくキャンセルを確認できます。

例

次の例は、Synchronize メソッドによる ISyncMgrSyncCallback::CanContinue の使用方法を示しています。

HRESULT CMyDeviceHandler::Synchronize(...)
{
    ...

    // Start synchronizing the sync items.

    ...

    // If a cancellation has been requested, stop the sync and exit.
    if (pCallback->CanContinue(pszItemID) == S_FALSE)
    {
        // End the sync operation and exit the function.
        hr = pCallback->ReportProgress(pszItemID,
                                       pszCancelMessage,
                                       SYNCMGR_PS_CANCELED,
                                       uCurrentStep,
                                       uMaxStep,
                                       NULL);
    }
    ...
}

同期の保留要求がある項目のセットの列挙子を取得します。これは、現在の同期が完了した後に同期される項目のセットです。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。保留中の項目がない場合は S_FALSE を返します。

取得した列挙子インターフェイスの Next メソッドの呼び出しで取得される項目 ID は、終端の null 文字を含めて最大長 MAX_SYNCMGR_ID です。呼び出し側のアプリケーションは、Next メソッドを通じて取得した各項目 ID を CoTaskMemFree を使用して解放する責任があります。

指定された項目を、現在同期中の項目のセットに追加します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。pszItemID がすでにセッションの一部である場合は E_INVALIDARG を返します。

ISyncMgrSyncCallback::AddItemToSession は同期ハンドラーによって呼び出されます。

例

次の例は、Synchronize メソッドによる ISyncMgrSyncCallback::AddItemToSession の使用方法を示しています。

HRESULT CMyDeviceHandler::Synchronize(...)
{
    ...

    // Start synchronizing the handler.

    ...

    // Check for additional items to sync.
    IEnumString *penumItemIDs = NULL;
    
    hr = pCallback->QueryForAdditionalItems(&penumItemIDs);
    if (hr == S_OK)
    {
        while (hr == S_OK)
        {
            LPWSTR pszItemID;
            ULONG cFetched;
            hr = penumItemIDs->Next(1, &pszItemID, &cFetched);
            if ((hr == S_OK) && (cFetched == 1))
            {
                // Add this item to the set of items we are syncing.
                hr = pCallback->AddItemToSession(pszItemID);
                CoTaskMemFree(pszItemID);
            }
        }
        penumItemIDs->Release();
    }
    ...
}

以前に列挙された項目のセットへの新しい項目の追加を提案します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。pszItemID がすでに存在する場合は E_INVALIDARG を返します。

ISyncMgrSyncCallback::ProposeItem は通常、項目が正常に同期されるまで同期セットの一部と見なされない場合に呼び出されます。Sync Center は、ISyncMgrSyncCallback::CommitItem メソッドが呼び出されるまで、この項目を UI に表示しません。

例

次の例は、Synchronize メソッドによる ISyncMgrSyncCallback::ProposeItem と ISyncMgrSyncCallback::CommitItem の使用方法を示しています。

HRESULT CMyDeviceHandler::Synchronize(...)
{
    ...

    // Start synchronizing the handler.

    ...

    // Find items waiting to be created.
    for (...)
    {
        // Create the item.
        ISyncMgrSyncItem *pNewItem = NULL;
        LPWSTR szItemID[MAX_SYNCMGR_ID];
        
        hr = GetNextNewItem(&pNewItem, szItemID, ARRAYSIZE(szItemID));
        if (SUCCEEDED(hr))
        {
            // Propose this item to Sync Center.
            hr = pCallback->ProposeItem(pNewItem);
            if (SUCCEEDED(hr))
            {
                // Synchronize the item.
                // Synchronization was successful.  Commit the item.
                hr = pCallback->CommitItem(szItemID);
            }
            pNewItem->Release();
        }
    }
    ...
}

指定された項目をハンドラーの同期セットのメンバーとして確定し、UI に表示すべきであることを確定します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。項目が最初に ISyncMgrSyncCallback::ProposeItem を通じて送信されていない場合、または項目がすでに現在のセッションの一部である場合は E_INVALIDARG を返します。

Sync Center の UI の外部から手動で要求された同期操作が実行されていることを報告します。

型: HRESULT

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