IWMDMStorage4

IWMDMStorage4 インターフェイスは IWMDMStorage3 を拡張し、ストレージで利用可能なメタデータのサブセットを取得するメソッドと、他のストレージへの参照の一覧を設定および取得するメソッドを提供します。

SetReferences メソッドは、参照を持つストレージ (プレイリストやアルバムなど) が保持する参照を設定します。そのストレージが以前に保持していた参照はすべて上書きされます。

このメソッドは HRESULT を返します。Windows Media Device Manager のすべてのインターフェイスメソッドは、次のいずれかの種類のエラーコードを返す可能性があります。

• 標準の COM エラーコード
• HRESULT 値に変換された Windows エラーコード
• Windows Media Device Manager のエラーコード

このメソッドは、プレイリストやアルバムのように参照によって構成されるオブジェクトに参照を設定するために使用します。デバイスがメタデータをサポートしていない場合、このメソッドはサポートされない可能性が高くなります。

ppIWMDMStorage 配列には、有効な IWMDMStorage オブジェクトであればどれでも格納できます。これには、フォルダーや、それ自体が参照を指定する他のストレージ (たとえばプレイリストのプレイリストを作成する場合) も含まれます。参照先オブジェクトの個々のケースをどのように扱うかは、デバイス自体が決定します。Windows Media Device Manager は、IWMDMStorage が有効であること以外のルールを強制しません。入れ子になったプレイリスト参照を含むプレイリストの場合を考えてみます。あるデバイスではこれは許可されず、SetReferences は失敗します。別のデバイスではこれが許可され、再生時には含まれる参照のセット全体を深さ優先の順にたどるだけです。

IWMDMStorage4 インターフェイスポインターが、デバイス上にすでに存在しないストレージに対応している状況が生じることがあります。この場合は WMDM_E_INTERFACEDEAD が返されます。

GetReferences メソッドは、このストレージが指している IWMDMStorage オブジェクトへのポインターの配列を取得します。抽象アルバムや抽象プレイリストは、通常 MTP デバイス上では参照のコレクションとして格納されます。

このメソッドは HRESULT を返します。Windows Media Device Manager のすべてのインターフェイスメソッドは、次のいずれかの種類のエラーコードを返す可能性があります。

• 標準の COM エラーコード
• HRESULT 値に変換された Windows エラーコード
• Windows Media Device Manager のエラーコード

Windows Media Device Manager は、ストレージ上の参照を追加および削除する処理を、基になるサービスプロバイダーに委譲します。参照を持つオブジェクトとは、抽象プレイリストや抽象アルバムのような抽象オブジェクトを指します。フォルダーは参照を持つものとは見なされません。

このメソッドでエラーの原因となる非同期の削除には 2 種類あります。アプリケーションがストレージへの参照を取得した後にその参照が削除され、アプリケーションがその参照を使用しようとした場合、メソッド呼び出しは WMDM_E_INTERFACEDEAD を返します。参照が指すファイルが削除されている場合は、S_FALSE が返されます。

例

次の C++ コードは、ストレージ (pStorage) の参照を照会します。

// 参照を取得します。
CComQIPtr<IWMDMStorage4> pStorage4(pStorage);
if (pStorage4 != NULL)
{
    WCHAR name[100];
    DWORD numRefs = 0;
    IWMDMStorage** parrReferences;
    hr = pStorage4->GetReferences(&numRefs, &parrReferences);
    for(int i = 0; i < numRefs; i++)
    {
        ZeroMemory(name, sizeof(name));
        hr = parrReferences[i]->GetName(name, (sizeof(name) / sizeof(WCHAR)) - 1);
        if (hr == S_OK)
            // TODO: 名前を表示します。
        parrReferences[i]->Release();
    }
    // メモリを解放します。
    if (parrReferences != NULL)
        CoTaskMemFree(parrReferences);
}

GetRightsWithProgress メソッドは、ストレージオブジェクトの権利情報を取得します。その際、進行状況を監視するためのコールバック機構を提供します。

このメソッドは HRESULT を返します。Windows Media Device Manager のすべてのインターフェイスメソッドは、次のいずれかの種類のエラーコードを返す可能性があります。

• 標準の COM エラーコード
• HRESULT 値に変換された Windows エラーコード
• Windows Media Device Manager のエラーコード

オブジェクトの権利は、デジタルメディアコンテンツの使用許諾を表します。たとえば WMDMRIGHTS 構造体には、ファイルを再生できる回数や、誰が再生できるかに関する情報を格納できます。

ライセンスされたファイルから権利を取得する処理は、時間がかかることがあります。この関数を使用すると、権利の要求を非同期に実行できます。

セキュアコンテンツプロバイダーは、進行状況の通知に加えて、コールバック pIProgressCallback 上でイベント通知を生成できます。このようなイベントの例としては、セキュアクロックの取得や DRM の初期化などがあります。これらのイベントについては IWMDMProgress3::Progress3 で説明しています。

このメソッドは IWMDMStorage::GetRights と同一ですが、進行状況を返す点と、パラメーター検証用の MAC を提供しない点が異なります。

GetSpecifiedMetadata メソッドは、ストレージから 1 つ以上の特定のメタデータプロパティを取得します。

このメソッドは HRESULT を返します。Windows Media Device Manager のすべてのインターフェイスメソッドは、次のいずれかの種類のエラーコードを返す可能性があります。

• 標準の COM エラーコード
• HRESULT 値に変換された Windows エラーコード
• Windows Media Device Manager のエラーコード

このメソッドを使用すると、クライアントはどのプロパティを取得するかを制御できます。これは IWMDMStorage3::GetMetadata よりも効率的な場合があり、クライアントがストレージでサポートされるプロパティのサブセットのみを必要とする場合に推奨されます。

このメソッドを使用して Windows Portable Devices (WPD) デバイスからデータを取得した場合、データは IPortableDeviceValues オブジェクト内にバイナリ形式で返されます。実際のプロパティ値を得るには、アプリケーションがこのデータを逆シリアル化する必要があります。

指定したプロパティの一部が取得できなかった場合でも、少なくとも 1 つのプロパティが取得できていれば、このメソッドは成功し WMDM_S_NOT_ALL_PROPERTIES_RETRIEVED を返します。指定したプロパティを 1 つも取得できなかった場合、このメソッドは失敗し WMDM_E_NOTSUPPORTED を返します。

単一のプロパティを要求する場合は、このメソッドの特殊なケースになります。クライアントが単一のプロパティを要求した場合、返される可能性のあるコードは S_OK、E_INVALIDARG、WMDM_E_NOTSUPPORTED です。したがって単一プロパティの場合、このメソッドはそのプロパティの取得に成功したときにのみ成功します。

FindStorage メソッドは、永続的な一意識別子に基づいて、現在のルートストレージ内のストレージを取得します。

このメソッドは HRESULT を返します。Windows Media Device Manager のすべてのインターフェイスメソッドは、次のいずれかの種類のエラーコードを返す可能性があります。

• 標準の COM エラーコード
• HRESULT 値に変換された Windows エラーコード
• Windows Media Device Manager のエラーコード

このメソッドは、デバイス上の単一のメモリオブジェクト (フラッシュカードまたはハードディスク) のみを検索します。

永続的な一意識別子は、特定のデバイスに格納されたコンテンツを識別します。すべてのデバイスで同一のまま保たれる、コンテンツ固有のグローバル一意識別子を表すものではありません。したがって、同じコンテンツであっても異なるストレージに格納されていれば、異なる永続的な一意識別子を持ちます。同様に、異なるコンテンツであっても、異なるデバイスに格納されている場合は同じ永続的な一意識別子を持つことがあります。

永続的な一意識別子の形式はデバイスによって異なります。アプリケーションは、あらかじめストレージを取得し、その WMDM/PersistentUniqueID プロパティを照会することで、永続的な一意識別子を取得しておく必要があります。このプロパティを要求するには、GetSpecifiedMetadata メソッドまたは GetMetadata メソッドを使用します。

GetParent メソッドは、ストレージの親を取得します。

このメソッドは HRESULT を返します。Windows Media Device Manager のすべてのインターフェイスメソッドは、次のいずれかの種類のエラーコードを返す可能性があります。

• 標準の COM エラーコード
• HRESULT 値に変換された Windows エラーコード
• Windows Media Device Manager のエラーコード

アプリケーションは、GetParent を再帰的に呼び出すことでストレージ階層をさかのぼることができます。ルートストレージに到達した後は、GetParent は S_FALSE を返し、ppStorage に NULL を設定します。

例

次の C++ 関数は、ストレージのルートの親までさかのぼります。

HRESULT BubbleUp(IWMDMStorage *pIStorage)
{
    HRESULT hr = S_OK;
    CComPtr<IWMDMStorage4> pStorage4;

    hr = pIStorage->QueryInterface (__uuidof(IWMDMStorage4), reinterpret_cast<void**>(&pStorage4));
    if (SUCCEEDED(hr))
    {
        while ((pStorage4 != NULL))
        {
            CComPtr<IWMDMStorage> pParent;
            hr = pStorage4->GetParent(&pParent);
            if (FAILED(hr))
            {
                break;
            }

            //
            // pParent に対して何らかの処理を行います....
            //
            
            if (S_FALSE != hr)
            {
                hr = pParent->QueryInterface (__uuidof(IMDSPStorage4), reinterpret_cast<void**>(&pStorage4));
                if (FAILED(hr))
                {
                    break;
                }
            }
        } // 次の親へループします。
    }

    return hr;
}