IWMDMStorage

IWMDMStorage インターフェイスのインスタンスは、デバイス上のストレージ(ファイル、フォルダー、プレイリストなど、データオブジェクトやコレクションオブジェクトの総称)を調査および探索するためのメソッドを提供します。

SetAttributes メソッドは、ストレージの属性を設定します。

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

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

GetAttributes に記載されている属性の多くは設定できないため、SetAttributes の属性表には記載されていません。

GetStorageGlobals メソッドは、このストレージのルートストレージの IWMDMStorageGlobals インターフェイスを取得します。

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

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

返される IWMDMStorageGlobals インターフェイスは、現在のストレージのルートストレージに関するグローバル情報へアクセスするためのメソッドを提供します。このインターフェイスはデバイスのグローバル情報を公開するため、アプリケーションは 1 つのメモリコンテナー内のいずれかのストレージに対して、このメソッドを一度呼び出すだけで済みます。

GetAttributes メソッドは、ストレージの属性を取得します。

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

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

GetName メソッドは、ストレージの表示名を取得します。

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

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

GetDate メソッドは、ストレージが最後に変更された日付を取得します。

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

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

時刻は協定世界時 (UTC) で指定されます。

例

次の C++ コードは、渡されたストレージから「最終更新日時」の値を取得します。

// 「最終更新日時」を取得します。
WMDMDATETIME lastModified;
hr = pStorage->GetDate(&lastModified);
// TODO: 最終更新の年月日を表示します。

GetSize メソッドは、ストレージのサイズをバイト単位で取得します。

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

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

フォルダーや抽象オブジェクト(抽象プレイリストなど)の場合、サイズは 0 です。

例

次の C++ コードは、ファイルのサイズをキロバイト単位で取得します。

// ファイルのサイズをキロバイト単位で取得します。
DWORD lowSize = 0;
DWORD highSize = 0;
hr = pStorage->GetSize(&lowSize, &highSize);
//TODO: ファイルサイズを表示します。

GetRights メソッドは、ライセンスされたストレージの権利情報を取得します。

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

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

オブジェクトの権利は、デジタルメディアコンテンツの使用許諾を表します。たとえば、WMDMRIGHTS 構造体には、ファイルを再生できる回数や再生できるユーザーに関する情報を格納できます。ライセンスされたファイルでない場合、このメソッドは失敗します。

ppRights 配列はこのメソッドによって割り当てられるため、アプリケーションは標準の Win32 関数である CoTaskMemFree を使用して解放する必要があります。

この呼び出しの進行状況イベントを受け取るには、IWMDMStorage4::GetRightsWithProgress を使用します。

このメソッドを呼び出した後、アプリケーションはパラメーターのメッセージ認証コード (MAC) 値を計算し、出力された MAC 値と比較することで、パラメーターが改ざんされていないことを確認できます。次のサンプルコードは、その一例を示しています。

例

CSecureChannelClient  *pSCClient;
IWMDMStorage  *pStorgae;

HMAC  hMAC;
BYTE  abMAC[WMDM_MAC_LENGTH];
BYTE  abMACVerify[WMDM_MAC_LENGTH];

hr = pStorage->GetRights(&pRights, &nRightsCount, abMAC);
if (SUCCEEDED(hr))
{
    //
    // まず、取得した権利の整合性を検証します。
    //
    pSCClient->MACInit(&hMAC);
    pSCClient->MACUpdate(hMAC, (BYTE*)(pRights), 
                    sizeof(WMDMRIGHTS) * nRightsCount);
    pSCClient->MACUpdate(hMAC, (BYTE*)(&nRightsCount), 
                                 sizeof(nRightsCount));
    pSCClient->MACFinal(hMAC, (BYTE*)abMACVerify);
    if (memcmp(abMACVerify, abMAC, sizeof(abMAC)) != 0)
    {
        hr = WMDM_E_MAC_CHECK_FAILED;
    }
}

EnumStorage メソッドは、現在のストレージの直下の子ストレージを列挙するために IWMDMEnumStorage インターフェイスを取得します。

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

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

取得される IWMDMEnumStorage インターフェイスは、このオブジェクトの直下の子を列挙します。このメソッドにより、アプリケーションはデバイスの内容を再帰的にたどることができます。

SendOpaqueCommand メソッドは、Windows Media Device Manager を介して、コマンドを処理せずにストレージへ送信します。

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

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

このメソッドは、Windows Media Device Manager の動作に影響を与えず、変更せずにそのまま渡すべきストレージメディアコマンドを対象としています。

例

次の C++ コードは、SendOpaqueCommand を呼び出して、デバイスとの簡単なカスタム認証手順を実行します。呼び出し元は自身の証明書と MAC をデバイスに送信し、デバイスは自身の証明書と MAC を返します。アプリケーションは、取得した証明書を保持している証明書と比較し、一致した場合(かつ MAC が正しい場合)に bExtraCertified を TRUE に設定します。

    // SendOpaqueCommand を呼び出して、拡張認証情報を交換します。
    {
        HMAC           hMAC;
        OPAQUECOMMAND  Command;
        CERTINFOEX    *pCertInfoEx;
        DWORD          cbData_App   = sizeof(bCertInfoEx_App)/sizeof(bCertInfoEx_App[0]);
        DWORD          cbData_SP    = sizeof(bCertInfoEx_SP)/sizeof(bCertInfoEx_SP[0]);
        DWORD          cbData_Send  = sizeof(CERTINFOEX) + cbData_App;

        // 不透明コマンド構造体にアプリケーションの証明書を設定します。
        memcpy(&(Command.guidCommand), &guidCertInfoEx, sizeof(GUID));

        Command.pData = (BYTE *)CoTaskMemAlloc(cbData_Send);
        if (!Command.pData)
        {
            ExitOnFail(hr = E_OUTOFMEMORY);
        }
        Command.dwDataLen = cbData_Send;

        // 不透明コマンド内のデータを CERTINFOEX 構造体にマップし、
        // 送信する証明書情報を設定します。
        pCertInfoEx = (CERTINFOEX *)Command.pData;
        pCertInfoEx->hr     = S_OK;
        pCertInfoEx->cbCert = cbData_App;
        memcpy(pCertInfoEx->pbCert, bCertInfoEx_App, cbData_App);

        // データの MAC を計算し、OPAQUECOMMAND 構造体に追加します。
        g_cWmdm.m_pSAC->MACInit(&hMAC);
        g_cWmdm.m_pSAC->MACUpdate(hMAC, (BYTE*)(&(Command.guidCommand)), sizeof(GUID));
        g_cWmdm.m_pSAC->MACUpdate(hMAC, (BYTE*)(&(Command.dwDataLen)), sizeof(Command.dwDataLen));
        if (Command.pData)
        {
            g_cWmdm.m_pSAC->MACUpdate(hMAC, Command.pData, Command.dwDataLen);
        }
        g_cWmdm.m_pSAC->MACFinal(hMAC, Command.abMAC);

        // 不透明コマンドを送信します。
        hr = pDevice->SendOpaqueCommand(&Command);
        if (SUCCEEDED(hr))
        {
            // 次に、取得した MAC を検証します。
            BYTE abMACVerify2[ WMDM_MAC_LENGTH ];
            g_cWmdm.m_pSAC->MACInit(&hMAC);
            g_cWmdm.m_pSAC->MACUpdate(hMAC, (BYTE*)(&(Command.guidCommand)), sizeof(GUID));
            g_cWmdm.m_pSAC->MACUpdate(hMAC, (BYTE*)(&(Command.dwDataLen)), sizeof(Command.dwDataLen));
            if (Command.pData)
            {
                g_cWmdm.m_pSAC->MACUpdate(hMAC, Command.pData, Command.dwDataLen);
            }
            g_cWmdm.m_pSAC->MACFinal(hMAC, abMACVerify2);

            // MAC が一致するか確認します。
            if (memcmp(abMACVerify2, Command.abMAC, WMDM_MAC_LENGTH) == 0)
            {
                 // 一致した場合は、取得した証明書を検証します。
                // 不透明コマンド内のデータを CERTINFOEX 構造体にマップします。
                //
                pCertInfoEx = (CERTINFOEX *)Command.pData;

                // この単純な拡張認証方式では、呼び出される側が
                // 完全に一致する証明書情報を提供する必要があります。
                //
                if ((pCertInfoEx->cbCert != cbData_SP) &&
                    (memcmp(pCertInfoEx->pbCert, bCertInfoEx_SP, cbData_SP) == 0))
                {
                    bExtraCertified = TRUE;
                }
            }
        }

        if (Command.pData)
        {
            CoTaskMemFree(Command.pData);
        }
    }