Метод 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. Во время endSession необходимо указать один и тот же тип (или комбинацию типов).

[in] pCtx

Необязательный указатель на буфер контекста сеанса, выделенный вызывающим объектом, для частного обмена данными между приложением и поставщиком услуг. Приложения, знакомые с базовым поставщиком услуг, могут использовать этот буфер для передачи в него данных, зависящих от контекста. Диспетчер устройств Windows Media не выполняет никаких действий с этим контекстом. Вызывающий объект отвечает за освобождение этого буфера.

[in] dwSizeCtx

Размер буфера контекста в байтах. Если размер равен 0, pCtx игнорируется. Если размер не равен нулю, pCtx должен быть допустимым указателем.

Возвращаемое значение

Метод возвращает HRESULT. Все методы интерфейса в Windows Media диспетчер устройств могут возвращать любой из следующих классов кодов ошибок:

Стандартные коды ошибок COM
Коды ошибок Windows, преобразованные в значения HRESULT
Коды ошибок диспетчер устройств Windows Media

Подробный список возможных кодов ошибок см. в разделе Коды ошибок.

Объединение нескольких операций в сеанс не приводит к тому, что все действия будут отложены и выполнены в группе; все действия (например, вызов метода Insert) по-прежнему будут выполняться синхронно, как вызывается. Вместо этого использование сеанса позволяет Windows Media диспетчер устройств компонентам (таким как поставщик безопасного содержимого и поставщик услуг) выполнять некоторые операции только один раз за сеанс, что обеспечивает повышение производительности. Например, во время передачи файла на устройство поставщик безопасного содержимого может получить сертификат устройства один раз в начале сеанса, а не один раз для каждой передачи файла.

Приложения могут вызывать BeginSession для объекта устройства Windows Media диспетчер устройств перед выполнением набора операций и 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.");