ISyncMgrHandler

同期ハンドラーが実装する主要インターフェイスを構成するメソッドを公開します。

ISyncMgrHandler は ISyncMgrSynchronize を置き換えるものです。以前の機能の一部は簡素化され、一部は他のインターフェイスへ移されました。詳細については各メソッドのページを参照してください。

ハンドラーの表示名を取得します。

型: HRESULT

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

ハンドラー名は同期センターフォルダーで System.DisplayName (PKEY_DisplayName) プロパティとしてアクセスされます。

同期センターは、UpdateHandler または UpdateHandlerCollection が呼び出されるたびにこのメソッドを呼び出します。ISyncMgrHandler::GetName が失敗するか空文字列を返した場合、ハンドラーは同期センターフォルダーに表示されず、同期センターはそのハンドラーの呼び出しを試みません。

文字列バッファーの割り当ては CoTaskMemAlloc を使用してハンドラーが行う責任があります。同期センターは CoTaskMemFree を通じてバッファーを解放します。

ISyncMgrHandler::GetName は、ハンドラー名を取得するための GetHandlerInfo の使用を置き換えます。

ハンドラーを説明するプロパティを取得します。

型: HRESULT

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

このメソッドが失敗した場合でも、ハンドラーは引き続き同期センターフォルダーに表示され、同期センターはそのハンドラーの呼び出しを続けますが、すべてのプロパティには既定値が使用されます。

ISyncMgrHandler::GetHandlerInfo は、ISyncMgrHandler::GetName とともに、以前の GetHandlerInfo を置き換えます。

例

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

STDMETHODIMP CMyDeviceHandler::GetHandlerInfo(
                             __out ISyncMgrHandlerInfo **ppHandlerInfo)
{
    *ppHandlerInfo = NULL;
    HRESULT hr = QueryInterface(IID_ISyncMgrHandlerInfo, 
                                (void **) ppHandlerInfo);
    return hr;
}

ハンドラーに関連する特定の種類のオブジェクトを作成します。

型: HRESULT

成功した場合は S_OK を返し、それ以外の場合はエラー値を返します。ハンドラーが要求された種類のオブジェクトをサポートしていない場合は E_NOTIMPL を返します。

ハンドラーは、要求されたインターフェイスを自身に実装することも、別のオブジェクトに実装することもできます。

例

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

STDMETHODIMP CMyDeviceHandler::GetObject( __in REFGUID   rguidObjectID, 
                                          __in REFIID    riid,
                                          __out void   **ppv)
{
    HRESULT hr = E_NOTIMPL;
    *ppv = NULL;

    if (rguidObjectID == SYNCMGR_OBJECTID_QueryBeforeActivate)
    {
        hr = _CreateSetupObject(riid, ppv);
    }
    else if (rguidObjectID == SYNCMGR_OBJECTID_EventStore)
    {
        hr = _CreateEventStore(NULL, riid, ppv);
    }

    return hr;
}

ハンドラーに定義された機能を表すフラグのセットを取得します。

型: HRESULT

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

このメソッドは、UpdateHandler または UpdateHandlerCollection への呼び出しに応じて同期センターによって呼び出されます。

例

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

STDMETHODIMP CMyDeviceHandler::GetCapabilities(
                             __out SYNCMGR_HANDLER_CAPABILITIES *pmCapabilities)
{
    *pmCapabilities = SYNCMGR_HCM_EVENT_STORE
                    | SYNCMGR_HCM_QUERY_BEFORE_ACTIVATE;
    return S_OK;
}

ハンドラーが設定したポリシーを表すフラグのセットを取得します。

型: HRESULT

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

ポリシーとは、通常はサポートされているものの、グループポリシーによって無効化できるアクションのことです。

このメソッドは、UpdateHandler または UpdateHandlerCollection への呼び出しに応じて同期センターによって呼び出されます。

例

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

STDMETHODIMP CMyDeviceHandler::GetPolicies(
                             __out SYNCMGR_HANDLER_POLICIES *pmPolicies)
{
    *pmPolicies = SYNCMGR_HPM_NONE;
    return S_OK;
}

ハンドラーの有効化または無効化を要求します。有効なハンドラーは同期できますが、無効なハンドラーは同期できません。

型: HRESULT

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

有効なハンドラーは同期センターフォルダーに表示され、同期できます。無効なハンドラーは同期セットアップフォルダーに表示され、同期する前に有効化する（これにより同期センターフォルダーへ移動します）必要があります。

有効化状態を有効/無効状態（enabled state）と混同しないでください。有効なハンドラーを無効（disabled）にすることはできます。これは、そのハンドラーが引き続き同期センターフォルダーに表示されるものの、同期できないことを意味します。

同期センターは次の2つの場合にこのメソッドを呼び出します。

• ユーザーが同期セットアップフォルダーでハンドラーを選択し、そのセットアップタスクを起動したとき。ハンドラーが SYNCMGR_OBJECTID_QueryBeforeActivate オブジェクトをサポートしている場合、このメソッドは、ハンドラーを有効化するかどうかをユーザーに確認するダイアログで構成される UI 操作が成功したときにのみ呼び出されます。
• ユーザーが同期センターフォルダーでハンドラーを選択し、その削除タスクを起動したとき。ただし、ハンドラーが SYNCMGR_HPM_PREVENT_DEACTIVATE フラグを設定していない場合に限ります。ハンドラーが SYNCMGR_OBJECTID_QueryBeforeDeactivate オブジェクトをサポートしている場合、このメソッドは UI 操作が成功したときにのみ呼び出されます。

個々のハンドラーの有効化状態は、IsActive を呼び出すことで確認できます。

ハンドラーが有効化時に何のアクションも実行する必要がない場合は、次の例に示すように S_OK または E_NOTIMPL のいずれかを返すことができます。

例

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

STDMETHODIMP CMyDeviceHandler::Activate(__in BOOL fActivate)
{
    return E_NOTIMPL;
}

有効なハンドラーの有効化(enable)または無効化(disable)を要求します。有効化されたハンドラーは同期でき、無効化されたハンドラーは同期できません。

型: HRESULT

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

ハンドラーが同期センターフォルダーに表示されるときに、そのショートカットメニューに有効化および無効化の項目を表示するには、ハンドラーが SYNCMGR_HCM_CAN_ENABLE および SYNCMGR_HCM_CAN_DISABLE フラグを設定する必要があります。ハンドラーを有効化することを選択すると同期できるようになり、無効化することを選択すると同期できなくなります。

同期センターは次の2つの場合にこのメソッドを呼び出します。

• ユーザーが同期センターフォルダーでハンドラーを選択し、その有効化タスクを起動したとき。ハンドラーが SYNCMGR_OBJECTID_QueryBeforeEnable オブジェクトをサポートしている場合、このメソッドは UI 操作が成功したときにのみ呼び出されます。
• ユーザーが同期センターフォルダーでハンドラーを選択し、その無効化タスクを起動したとき。ハンドラーが SYNCMGR_OBJECTID_QueryBeforeDisable オブジェクトをサポートしている場合、このメソッドは UI 操作が成功したときにのみ呼び出されます。

例

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

STDMETHODIMP CMyDeviceHandler::Enable(__in BOOL fEnable)
{
    return E_NOTIMPL;
}

ハンドラーの同期項目の中から選択された項目の同期を開始します。

型: HRESULT

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

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

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

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

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

ISyncMgrHandler::Synchronize メソッドが呼び出された後、ユーザーが追加の項目の同期を要求した場合、ハンドラーはコールバックの QueryForAdditionalItems メソッドを通じてそれらを問い合わせることで、同じセッション内で新しい項目を同期できます。問い合わせた項目を同期することを選択した場合、AddItemToSession を呼び出すことができます。

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

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

ISyncMgrHandler::Synchronize と Synchronize のもう1つの違いは、以前のメソッドが同期を非同期に実行することを期待されていた点です。Synchronize は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;
}