IWMDMDeviceSession::BeginSession メソッド (mswmdm.h)

[アーティクル]
08/25/2023

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

構文

HRESULT BeginSession(
  [in] WMDM_SESSION_TYPE type,
  [in] BYTE              *pCtx,
  [in] DWORD             dwSizeCtx
);

パラメーター

[in] type

開始するセッションの種類を説明する WMDM_SESSION_TYPE 。これは、WMDM_SESSION_NONEを除くすべての値のビットごとの OR です。 EndSession では、同じ型 (または型の組み合わせ) を指定する必要があります。

[in] pCtx

アプリケーションとサービスプロバイダー間のプライベート通信用の呼び出し元によって割り当てられたセッションコンテキストバッファーへのオプションのポインター。基になるサービスプロバイダーに関する知識を持つアプリケーションでは、このバッファーを使用してコンテキスト固有のデータを渡すことができます。 Windows Media デバイスマネージャーでは、このコンテキストでは何も行われません。呼び出し元は、このバッファーを解放する役割を担います。

[in] dwSizeCtx

コンテキストバッファーのサイズ (バイト単位)。サイズが 0 の場合、 pCtx は無視されます。サイズが 0 以外の場合、 pCtx は有効なポインターである必要があります。

戻り値

このメソッドは HRESULT を返します。 Windows Media デバイスマネージャーのすべてのインターフェイスメソッドは、次のいずれかのエラーコードクラスを返すことができます。

標準 COM エラーコード
HRESULT 値に変換された Windows エラーコード
Windows Media デバイスマネージャーエラーコード

考えられるエラーコードの詳細な一覧については、「エラーコード」を参照してください。

注釈

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

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

アプリケーションは通常、複数のファイル転送または削除中に BeginSession を呼び出します。これに応じて、Windows Media デバイスマネージャーは、セキュリティで保護されたコンテンツプロバイダーとサービスプロバイダーで BeginSession または EndSession を呼び出します。応答として、セキュリティで保護されたコンテンツプロバイダーとサービスプロバイダーは、セッションごとに 1 回の操作を実行できます。これらのコンポーネントのいずれかでセッションを開く際に失敗した場合、Windows Media デバイスマネージャーはコンポーネントから返されたエラーを返します。

セッションは、デバイスごとに実装されます。異なるデバイス上のセッションは相互に干渉しません。

セッションには次の制限が適用されます。

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

WMDM_SESSION_TRANSFER_TO_DEVICE |WMDM_SESSION_DELETE

次に、EndSession もで呼び出す必要があります

WMDM_SESSION_TRANSFER_TO_DEVICE |WMDM_SESSION_DELETE

それ以外の場合、Windows Media デバイスマネージャーはE_INVALIDARGを返します。
Windows Media デバイスマネージャーセッションは、単に最適化のためのブラケットメカニズムであり、デバイスのロックや所有権に関する影響はありません。サービスプロバイダーまたは下位レベルのデバイスドライバーでは、さまざまな Windows Media デバイスマネージャーアプリケーションによって発生する可能性があるデバイスアクセスを同期する必要があります。

例

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


// Get the session interface.
CComQIPtr<IWMDMDeviceSession> pSession(pDevice);
if (pDevice == NULL)
{
    // TODO: Display a message that the application couldn't get an 
    // IWMDMDeviceSession interface.
    return E_NOINTERFACE;
}

// Start the session. We don't use a custom buffer.
hr = pSession->BeginSession(WMDM_SESSION_TRANSFER_TO_DEVICE, NULL, NULL);
if (hr != S_OK)
{
    // TODO: Display a message indicating that the session failed to start.
    return hr;
}
else
{
    // TODO: Display a message that the session started.
}


// Insert files. These calls happen synchronously.
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, // Use default name.
        NULL, // Don't specify IWMDMOperation.
        NULL, // Don't specify IWMDMProgress.
        NULL, // Don't specify metadata.
        NULL, // Nothing to send to the 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");
}

// Close the session.
hr = pSession->EndSession(WMDM_SESSION_TRANSFER_TO_DEVICE, NULL, NULL);
CHECK_HR(hr,"Closed the session.","Couldn't close the session.");