iWMDMDeviceSession：：BeginSession 方法 (mswmdm.h)

项目
03/05/2024

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 。如果大小不为零， 则 pCtx 必须是有效的指针。

返回值

该方法返回 HRESULT。 Windows Media 设备管理器中的所有接口方法都可以返回以下任一类错误代码：

标准 COM 错误代码
转换为 HRESULT 值的 Windows 错误代码
Windows Media 设备管理器错误代码

有关可能错误代码的广泛列表，请参阅错误代码。

注解

将多个操作捆绑到一个会话中不会导致所有操作被推迟并在一个组中执行; (调用 Insert) 等所有操作仍将按调用方式同步执行。相反，使用会话可让 Windows Media 设备管理器组件 (例如安全内容提供程序和服务提供商) 每个会话仅执行一次某些操作，从而改进性能。例如，在文件传输到设备期间，安全内容提供程序可以在会话开始时获取设备证书一次，而不是每次文件传输一次。

应用程序可以在执行一组操作之前对 Windows Media 设备管理器设备对象调用 BeginSession，并在完成后调用 EndSession。

应用程序通常在多次文件传输或删除期间调用 BeginSession 。为此，Windows Media 设备管理器对安全内容提供程序和服务提供商调用 BeginSession 或 EndSession。作为响应，安全内容提供程序和服务提供程序可以为每个会话执行一次操作。如果在任何这些组件上打开会话失败，Windows Media 设备管理器将返回组件返回的失败。

会话基于每个设备实现。不同设备上的会话不会相互干扰。

以下限制适用于会话：

对于特定设备，一次只能有一个会话处于活动状态。尝试在设备上打开多个会话将导致错误。
会话类型可以组合在一起。必须在 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.");