ISyncMgrHandlerInfo

ハンドラーが Sync Center にプロパティおよび状態情報を提供できるようにするメソッドを公開します。

ハンドラーは、通常 ISyncMgrHandler を実装するのと同じオブジェクト上で、このインターフェイスを常に実装する必要があります。ISyncMgrHandlerInfo を実装することで、ハンドラーを再コンパイルすることなくプロパティのセットを変更できます。また、プロパティへの型安全なアクセスも提供します。

Sync Center 向けのハンドラー種別を取得します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。メソッドが失敗した場合、pnType は SYNCMGR_HT_UNSPECIFIED に設定されます。

通常、この値は変化しません。ただし、Sync Center は UpdateHandler メソッドが呼び出されるたびにこのメソッドを呼び出します。

例

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

STDMETHODIMP CMyDeviceHandler::GetType(__out SYNCMGR_HANDLER_TYPE *pnType)
{
    *pnType = SYNCMGR_HT_DEVICE;
    return S_OK;

ハンドラー種別のラベルを取得します。通常、これはデバイスのモデル名、またはそれに相当するハンドラー固有の識別文字列を提供します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。メソッドが失敗した場合、ppszTypeLabel は空文字列を格納します。

ラベル値は、フォルダー UI において System.Sync.HandlerTypeLabel (PKEY_Sync_HandlerTypeLabel) プロパティとして表示されます。Sync Center は UpdateHandler メソッドが呼び出されるたびにこのメソッドを呼び出します。

ハンドラーは、ppszTypeLabel が指す文字列バッファーを CoTaskMemAlloc を通じて割り当てる責任があります。Sync Center は CoTaskMemFree を通じてその文字列バッファーを解放します。

例

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

STDMETHODIMP CMyDeviceHandler::GetTypeLabel(__out LPWSTR *ppszTypeLabel)
{
    LPWSTR pszTypeLabel = NULL;

    HRESULT hr = LoadStringAlloc(g_hmodThisDll, 
                                 IDS_HANDLER_TYPE_LABEL,
                                 &pszTypeLabel);
    if (SUCCEEDED(hr))
    {
        // Duplicate for the caller.
        hr = SHCoAllocString(pszTypeLabel, ppszTypeLabel);
        LocalFree(pszTypeLabel);
    }

    return hr;
}

ハンドラーに関する注釈を含む文字列を取得します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。メソッドが失敗した場合、ppszComment は空文字列を格納します。

この文字列は、パートナーシップの内容の概要を表示するためにハンドラーが提供できます。たとえば「32 件の連絡先」や「13 曲」などです。この文字列は、終端の null 文字を含めて最大長 MAX_SYNCMGR_NAME を持つことができます。

コメント値は、同期が実行されていないときにフォルダー UI において System.Sync.Comments (PKEY_Sync_Comments) プロパティとして表示されます。

Sync Center は UpdateHandler メソッドが呼び出されるたびにこのメソッドを呼び出します。

ハンドラーは、ppszComment が指す文字列バッファーを CoTaskMemAlloc を通じて割り当てる責任があります。Sync Center は CoTaskMemFree を通じてその文字列バッファーを解放します。

ハンドラーが最後に同期された日時を取得します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。メソッドが失敗した場合、pftLastSync は前回の同期の値を指します。

この値は既定ではフォルダー UI に表示されませんが、System.Sync.DateSynchronized (PKEY_Sync_DateSynchronized) プロパティとして利用できます。

Sync Center は UpdateHandler メソッドが呼び出されるたびにこのメソッドを呼び出します。

例

次の例は、時刻と日付を取得するためにプライベートなクラス関数を呼び出す、このメソッドの実装を示しています。

STDMETHODIMP CMyDeviceHandler::GetLastSyncTime(__out FILETIME *pftLastSync)
{
    *pftLastSync = _ftLastSync;
    return S_OK;
}

ハンドラーが同期可能かどうかを示す値を取得します。

型: HRESULT

ハンドラーがアクティブな場合は S_OK を、それ以外の場合は S_FALSE を返します。

ハンドラーが Sync Center に現在の状態を維持させたい場合は、E_NOTIMPL を返すことができます。それ以外の値が返された場合、Sync Center はハンドラーの状態を最後に判明している値に設定します。その状況でハンドラーの最後に判明している値が非アクティブであった場合、Sync Center は Setup タスクを無効にします。ハンドラーの最後に判明している値がアクティブであった場合、Delete タスクは無効になりません。

GetCapabilities から返されるマスクに SYNCMGR_HCM_QUERY_BEFORE_ACTIVATE または SYNCMGR_HCM_QUERY_BEFORE_DEACTIVE フラグのいずれかが設定されている場合、ハンドラーは自身のアクティブ化状態を管理する必要があるため、S_OK または S_FALSE のいずれかを返す必要があります。それ以外の戻り値はエラーとみなされます。

ハンドラーがアクティブでない場合、それは Sync Setup フォルダーに表示されます。そのフォルダー内のハンドラーは同期できません。ハンドラーを Sync Center フォルダーへ移動するには、ユーザーはハンドラーのショートカット メニューまたはコマンド モジュールから Setup タスクを選択します。

ハンドラーがアクティブな場合、それはメインの Sync Center フォルダーに表示されます。アクティブなハンドラーは、ユーザーによって、または ISyncMgrControl インターフェイスを通じて同期できます。ハンドラーを Sync Setup フォルダーへ移動するには、ユーザーはハンドラーのショートカット メニューまたはコマンド モジュールから Delete タスクを選択します。

Sync Center は UpdateHandler メソッドが呼び出されるたびにこのメソッドを呼び出します。

例

次の例は、アクティブ状態を取得するためにプライベートなクラス関数を呼び出す、このメソッドの実装を示しています。

STDMETHODIMP CMyDeviceHandler::IsActive()
{
    // Return a previously-calculated value.
    return (_fIsActive ? S_OK : S_FALSE);
}

ハンドラーが有効かどうかを示す値を取得します。

型: HRESULT

ハンドラーが有効な場合は S_OK を、それ以外の場合は S_FALSE を返します。

ハンドラーが Sync Center に現在の状態を維持させたい場合は、E_NOTIMPL を返すことができます。それ以外の値が返された場合、Sync Center はハンドラーの有効状態を最後に判明している値に設定し、関連するタスクを適切に有効または無効にします。

GetCapabilities から返されるマスクに SYNCMGR_HCM_QUERY_BEFORE_ENABLE または SYNCMGR_HCM_QUERY_BEFORE_DISABLE フラグのいずれかが設定されている場合、ハンドラーは自身の有効状態を管理する必要があるため、S_OK または S_FALSE のいずれかを返す必要があります。それ以外の戻り値はエラーとみなされます。

ハンドラーが無効な場合、そのハンドラー自体もその項目のいずれも Sync Center によって同期されません。また、Sync など、ハンドラーで利用可能な多くの操作が Sync Center フォルダー UI から削除または無効化されます。

この値は、フォルダー UI において System.Sync.Enabled (PKEY_Sync_Enabled) プロパティとして利用できます。

Sync Center は UpdateHandler メソッドが呼び出されるたびにこのメソッドを呼び出します。

例

次の例は、有効状態を取得するためにプライベートなクラス関数を呼び出す、このメソッドの実装を示しています。

STDMETHODIMP CMyDeviceHandler::IsEnabled()
{
    // Return a previously-calculated value.
    return (_fIsEnabled ? S_OK : S_FALSE);
}

ハンドラー(通常は何らかの種類の外部デバイス)が接続されているかどうかを示す値を取得します。

型: HRESULT

ハンドラーが接続されている場合は S_OK を、それ以外の場合は S_FALSE を返します。このメソッドが返すエラーは S_OK として解釈されます。

ハンドラーが切断されている場合、そのハンドラー自体もその項目のいずれも Sync Center によって同期されません。また、Sync など、ハンドラーで利用可能な多くの操作が Sync Center フォルダー UI から削除または無効化されます。

この値は、フォルダー UI において System.Sync.Connected (PKEY_Sync_Connected) プロパティとして利用できます。

Sync Center は UpdateHandler メソッドが呼び出されるたびにこのメソッドを呼び出します。

例

次の例は、接続状態を取得するためにプライベートなクラス関数を呼び出す、このメソッドの実装を示しています。

STDMETHODIMP CMyDeviceHandler::IsConnected()
{
    return (_IsConnected() ? S_OK : S_FALSE);
}