ISyncMgrSyncItem

単一の同期アイテムに作用し、そこから情報を取得するメソッドを公開します。これにより、ハンドラーは同期アイテムを独立したオブジェクトとして管理できます。

同期アイテムは通常、データのグループ(たとえば複数のファイルを含むフォルダー)を表します。この同期アイテムをインターフェイスとして表現することで、アイテムをオブジェクトとして容易に管理・実装できます。そのオブジェクトは、アイテムがアクセスされたときにアイテムの状態を保持します。

同期アイテムを ISyncMgrSyncItem として表現することで、他の同期アイテムを含む同期アイテムをサポートすることも可能になります。

同期アイテムの一意な ID を取得します。

型: HRESULT

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

このメソッドで取得される ID は変更できません。通常、ID は GUID 文字列の形式ですが、これは必須ではありません。ID は、ハンドラーのコンテキスト内で一意である限り、任意の文字列で構いません。

GetItemID が失敗するか、ppszItemID に空文字列が返された場合、その同期アイテムはハンドラーのフォルダーに表示されず、同期センターはそのアイテムを同期しようとしません。

このメソッドで取得される ID は、フォルダー UI で System.Sync.ItemID (PKEY_Sync_HandlerID) プロパティとして利用できます。

アイテムは、ppszComment が指す文字列バッファーを CoTaskMemAlloc によって割り当てる責任を負います。同期センターは、CoTaskMemFree によってその文字列バッファーを解放します。

古いバージョンの Sync Manager の実装では、このデータは SYNCMGRITEM 構造体を通じて取得されていました。

例

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

STDMETHODIMP CMyDeviceSyncItem::GetItemID(__out LPWSTR *ppszItemID)
{
    HRESULT hr = S_OK;
    *ppszName = NULL;

    // Generate the string version of the ID.
    if (_pszItemID == NULL)
    {
        LPOLESTR pszItemID = NULL;
        hr = StringFromCLSID(_guidItemID, &_pszItemID);
    }

    if (SUCCEEDED(hr))
    {
        // Duplicate the item ID string for the caller.
        hr = SHCoAllocString(_pszItemID, ppszItemID);
    } 

    return hr;
}

同期アイテムの UI 表示名を取得します。

型: HRESULT

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

GetName が失敗するか、ppszItemID に空文字列が返された場合、その同期アイテムはハンドラーのフォルダーに表示されず、同期センターはそのアイテムを同期しようとしません。

このメソッドで取得される ID は、ハンドラーのフォルダー UI で System.DisplayName (PKEY_DisplayName) プロパティとして利用できます。

アイテムは、ppszComment が指す文字列バッファーを CoTaskMemAlloc によって割り当てる責任を負います。同期センターは、CoTaskMemFree によってその文字列バッファーを解放します。

同期センターは、UpdateItem メソッドが呼び出されるたびに、このメソッドを呼び出します。

古いバージョンの Sync Manager の実装では、この情報は SYNCMGRHANDLERINFO 構造体を通じて取得されていました。

例

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

STDMETHODIMP CMyDeviceSyncItem::GetName(__out LPWSTR *ppszName)
{
    *ppszName = NULL;
    HRESULT hr = SHCoAllocString(_pszItemName, ppszName);
    return hr;
}

同期アイテムのプロパティを取得します。

型: HRESULT

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

GetItemInfo が失敗しても、その同期アイテムはハンドラーのフォルダーに引き続き表示され、同期センターは引き続き同期を行いますが、すべてのプロパティには既定値が使用されます。

例

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

STDMETHODIMP CMyDeviceSyncItem::GetItemInfo(
                              __out ISyncMgrSyncItemInfo **ppItemInfo)
{
    *ppItemInfo = NULL;
    
    HRESULT hr = QueryInterface(IID_ISyncMgrSyncItemInfo, (void**)ppItemInfo);
    return hr;
}

アイテムに関連する特定の種類のオブジェクトを作成します。

型: HRESULT

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

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

例

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

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

    if (rguidObjectID == SYNCMGR_OBJECTID_QueryBeforeDelete)
    {
        hr = _CreateQueryBeforeDeleteObject(riid, ppv);
    }
    else if (rguidObjectID == SYNCMGR_OBJECTID_EventStore)
    {
        hr = _CreateEventStore(_pszItemID, riid, ppv);
    }

    return hr;
}

アイテムに定義された機能を記述するフラグのセットを取得します。

型: HRESULT

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

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

例

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

STDMETHODIMP CMyDeviceSyncItem::GetCapabilities(
                              __out SYNCMGR_ITEM_CAPABILITIES *pmCapabilities)
{
    *pmCapabilities = SYNCMGR_ICM_EVENT_STORE
                    | SYNCMGR_ICM_CAN_DELETE
                    | SYNCMGR_ICM_QUERY_BEFORE_DELETE;
    
    return S_OK;
}

アイテムによって設定されたポリシーを記述するフラグのセットを取得します。

型: HRESULT

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

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

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

例

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

STDMETHODIMP CMyDeviceSyncItem::GetPolicies(
                              __out SYNCMGR_ITEM_POLICIES *pmPolicies)
{
    *pmPolicies = SYNCMGR_IPM_PREVENT_DISABLE 
                | SYNCMGR_IPM_HIDDEN_BY_DEFAULT;
                
    return S_OK;
}

同期アイテムを有効または無効にします。

型: HRESULT

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

同期センターは、次のシナリオでこのメソッドを呼び出します。

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

例

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

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

同期アイテムを削除します。

型: HRESULT

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

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

ハンドラーがアクティブ化されたときに何もアクションを実行する必要がない場合は、S_OK または E_NOTIMPL のいずれかを返すことができます。