Método IWMDMDeviceSession::BeginSession (mswmdm.h)

Artículo
03/15/2023

El método BeginSession inicia una sesión de dispositivo.

Sintaxis

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

Parámetros

[in] type

Un WMDM_SESSION_TYPE que describe el tipo de sesión que se va a iniciar. Se trata de un OR bit a bit de cualquier valor excepto WMDM_SESSION_NONE. Se debe especificar el mismo tipo (o combinación de tipos) durante EndSession.

[in] pCtx

Puntero opcional a un búfer de contexto de sesión asignado por el autor de la llamada para la comunicación privada entre la aplicación y el proveedor de servicios. Las aplicaciones que tienen conocimiento del proveedor de servicios subyacente pueden usar este búfer para pasar datos específicos del contexto. Windows Media Administrador de dispositivos no hace nada con este contexto. El autor de la llamada es responsable de liberar este búfer.

[in] dwSizeCtx

Tamaño del búfer de contexto, en bytes. Si el tamaño es 0, se omite pCtx . Si el tamaño es distinto de cero, pCtx debe ser un puntero válido.

Valor devuelto

El método devuelve un valor HRESULT. Todos los métodos de interfaz de Windows Media Administrador de dispositivos pueden devolver cualquiera de las siguientes clases de códigos de error:

Códigos de error COM estándar
Códigos de error de Windows convertidos en valores HRESULT
Códigos de error de windows Media Administrador de dispositivos

Para obtener una lista extensa de posibles códigos de error, consulte Códigos de error.

Comentarios

La agrupación de varias operaciones en una sesión no hace que todas las acciones se posponga y se realicen en un grupo; Todas las acciones (como una llamada a Insert) se seguirán realizando de forma sincrónica como se llama. En su lugar, el uso de una sesión permite a Windows Media Administrador de dispositivos componentes (como el proveedor de contenido seguro y el proveedor de servicios) realizar algunas de las operaciones solo una vez por sesión, lo que proporciona mejoras de rendimiento. Por ejemplo, durante la transferencia de archivos a un dispositivo, el proveedor de contenido seguro puede adquirir el certificado de dispositivo una vez al principio de la sesión en lugar de una vez para cada transferencia de archivos.

Las aplicaciones pueden llamar a BeginSession en un objeto de dispositivo de Windows Media Administrador de dispositivos antes de realizar un conjunto de operaciones y EndSession cuando terminen.

Normalmente, la aplicación llama a BeginSession durante varias transferencias de archivos o eliminaciones. En respuesta a esto, Windows Media Administrador de dispositivos llama a BeginSession o EndSession en el proveedor de contenido seguro y el proveedor de servicios. En respuesta, el proveedor de contenido seguro y el proveedor de servicios pueden realizar operaciones una vez por sesión. Si se produce un error al abrir la sesión en cualquiera de estos componentes, Windows Media Administrador de dispositivos devuelve un error devuelto por el componente.

Las sesiones se implementan por dispositivo. Las sesiones en diferentes dispositivos no interfieren entre sí.

Las restricciones siguientes se aplican a las sesiones:

Solo una sesión puede estar activa a la vez para un dispositivo determinado. Si se intenta abrir más de una sesión en un dispositivo, se producirá un error.
Los tipos de sesión se pueden combinar. Se debe especificar el mismo conjunto de marcas durante BeginSession y EndSession. Por lo tanto, no es posible finalizar solo parte de la sesión.
Por ejemplo, si se llama a BeginSession con

WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

A continuación, también se debe llamar a EndSession con

WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

De lo contrario, windows Media Administrador de dispositivos devolverá E_INVALIDARG.
Las sesiones de Administrador de dispositivos de Windows Media son simplemente un mecanismo de corchete para las optimizaciones y no tienen ninguna implicación en cuanto al bloqueo o la propiedad del dispositivo. El proveedor de servicios o el controlador de dispositivo de nivel inferior seguirán necesitando sincronizar el acceso al dispositivo que puede resultar de diferentes aplicaciones de Windows Media Administrador de dispositivos.

Ejemplos

El siguiente código de C++ muestra el uso de una sesión para agrupar una llamada Insert3 en un dispositivo. El código recorre una serie de archivos almacenados en un vector y los envía al dispositivo.


// 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.");