IWMDMDeviceSession

IWMDMDeviceSession インターフェイスは、複数の操作を 1 つのセッションにまとめることで、デバイス操作の効率を向上させます。

BeginSession メソッドは、デバイスセッションを開始します。

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

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

複数の操作を 1 つのセッションにまとめても、すべての動作が延期されてまとめて実行されるわけではありません。すべての動作 (Insert の呼び出しなど) は、呼び出された時点で引き続き同期的に実行されます。セッションを使用する目的は、Windows Media Device Manager のコンポーネント (セキュアコンテンツプロバイダーやサービスプロバイダーなど) が一部の操作をセッションごとに 1 回だけ実行できるようにし、パフォーマンスを向上させることにあります。たとえば、デバイスへのファイル転送中に、セキュアコンテンツプロバイダーはデバイス証明書をファイル転送ごとではなく、セッションの開始時に 1 回だけ取得できます。

アプリケーションは、一連の操作を行う前に Windows Media Device Manager のデバイスオブジェクトに対して BeginSession を呼び出し、完了したら EndSession を呼び出すことができます。

アプリケーションは通常、複数のファイル転送や削除を行う際に BeginSession を呼び出します。これに応じて、Windows Media Device Manager はセキュアコンテンツプロバイダーおよびサービスプロバイダーに対して BeginSession または EndSession を呼び出します。それを受けて、セキュアコンテンツプロバイダーとサービスプロバイダーは、セッションごとに 1 回だけ必要な処理を実行できます。これらのコンポーネントのいずれかでセッションの開始に失敗した場合、Windows Media Device Manager はそのコンポーネントが返したエラーを返します。

セッションはデバイス単位で実装されています。異なるデバイス上のセッションが互いに干渉することはありません。

セッションには次の制限があります。

1. 特定のデバイスに対して同時にアクティブにできるセッションは 1 つだけです。1 つのデバイスで複数のセッションを開こうとするとエラーになります。
2. セッションの種類は組み合わせられます。BeginSession と EndSession では同じフラグの組み合わせを指定する必要があります。したがって、セッションの一部だけを終了することはできません。

   たとえば、BeginSession を次の値で呼び出した場合

   WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

   EndSession も次の値で呼び出す必要があります。

   WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

   そうしない場合、Windows Media Device Manager は E_INVALIDARG を返します。

3. Windows Media Device Manager のセッションは最適化のための単なる囲い込み機構であり、デバイスのロックや所有権に関する意味を持ちません。異なる Windows Media Device Manager アプリケーションから発生し得るデバイスアクセスの同期は、引き続きサービスプロバイダーまたは下位のデバイスドライバーで行う必要があります。

例

次の C++ コードは、セッションを使用してデバイスへの Insert3 呼び出しをまとめる方法を示しています。このコードは、ベクターに格納された複数のファイルをループで処理し、デバイスに送信します。

// セッションインターフェイスを取得します。
CComQIPtr<IWMDMDeviceSession> pSession(pDevice);
if (pDevice == NULL)
{
    // TODO: IWMDMDeviceSession インターフェイスを取得できなかったことを示す
    // メッセージを表示します。
    return E_NOINTERFACE;
}

// セッションを開始します。カスタムバッファーは使用しません。
hr = pSession->BeginSession(WMDM_SESSION_TRANSFER_TO_DEVICE, NULL, NULL);
if (hr != S_OK)
{
    // TODO: セッションの開始に失敗したことを示すメッセージを表示します。
    return hr;
}
else
{
    // TODO: セッションが開始したことを示すメッセージを表示します。
}


// ファイルを挿入します。これらの呼び出しは同期的に行われます。
UINT flags = WMDM_MODE_BLOCK | WMDM_STORAGECONTROL_INSERTINTO | WMDM_FILE_CREATE_OVERWRITE | WMDM_CONTENT_FILE;
CComPtr<IWMDMStorage> pNewStorage;
for(int i = 0; i < sourceFiles.size(); i++)
{
    hr = pStorageControl3->Insert3(
        flags,
        WMDM_FILE_ATTR_FOLDER,
        sourceFiles[i],
        NULL, // 既定の名前を使用します。
        NULL, // IWMDMOperation は指定しません。
        NULL, // IWMDMProgress は指定しません。
        NULL, // メタデータは指定しません。
        NULL, // SCP に送るものはありません。
        &pNewStorage);

    if (pNewStorage != NULL)
        pNewStorage.Release();
    CHECK_HR(hr, "Sent file " << sourceFiles[i] << " to the device.", "Couldn't send file " << sourceFiles[i] << " to the device");
}

// セッションを閉じます。
hr = pSession->EndSession(WMDM_SESSION_TRANSFER_TO_DEVICE, NULL, NULL);
CHECK_HR(hr,"Closed the session.","Couldn't close the session.");

EndSession メソッドは、デバイスセッションを終了します。

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

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

セッションはデバイスに対する一連の操作を囲い込み、Windows Media Device Manager のコンポーネントが共通のセットアップ処理や終了処理を個々の転送ごとではなく 1 回だけ実行することで、パフォーマンスを最適化できるようにします。詳細については BeginSession を参照してください。

EndSession の呼び出しに応じて、Windows Media Device Manager はセキュアコンテンツプロバイダーおよびサービスプロバイダーに対して EndSession を呼び出します。いずれかで呼び出しが失敗した場合、Windows Media Device Manager はエラーを返します。その場合でも、いずれかのコンポーネントでは EndSession が成功している可能性があります。

例

次の C++ コードは、セッションを使用してデバイスへの Insert3 呼び出しをまとめる方法を示しています。このコードは、ベクターに格納された複数のファイルをループで処理し、デバイスに送信します。

// セッションインターフェイスを取得します。
CComQIPtr<IWMDMDeviceSession> pSession(pDevice);
if (pDevice == NULL)
{
    // TODO: アプリケーションが IWMDMDeviceSession インターフェイスを取得できなかったことを示すメッセージを表示します。
    return E_NOINTERFACE;
}

// セッションを開始します。カスタムバッファーは使用しません。
hr = pSession->BeginSession(WMDM_SESSION_TRANSFER_TO_DEVICE, NULL, NULL);
if (hr != S_OK)
{
    / /TODO: セッションの開始に失敗したことを示すメッセージを表示します。
    return hr;
}
else
{
    // TODO: セッションが開始したことを示すメッセージを表示します。
}


// ファイルを挿入します。これらの呼び出しは同期的に行われます。
UINT flags = WMDM_MODE_BLOCK | WMDM_STORAGECONTROL_INSERTINTO | WMDM_FILE_CREATE_OVERWRITE | WMDM_CONTENT_FILE;
CComPtr<IWMDMStorage> pNewStorage;
for(int i = 0; i < sourceFiles.size(); i++)
{
    hr = pStorageControl3->Insert3(
        flags,
        WMDM_FILE_ATTR_FOLDER,
        sourceFiles[i],
        NULL, // 既定の名前を使用します。
        NULL, // IWMDMOperation は指定しません
        NULL, // IWMDMProgress は指定しません
        NULL, // メタデータは指定しません
        NULL, // SCP に送るものはありません。
        &pNewStorage);

    if (pNewStorage != NULL)
        pNewStorage.Release();
    CHECK_HR(hr, "Sent file " << sourceFiles[i] << " to the device.", "Couldn't send file " << sourceFiles[i] << " to the device");
}

// セッションを閉じます。
hr = pSession->EndSession(WMDM_SESSION_TRANSFER_TO_DEVICE, NULL, NULL);
CHECK_HR(hr,"Closed the session.","Couldn't close the session.");