Compartilhar via

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

  • Artigo

O método BeginSession inicia uma sessão de dispositivo.

Sintaxe

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

Parâmetros

[in] type

Um WMDM_SESSION_TYPE que descreve o tipo de sessão a ser iniciada. Esse é um OR bit a bit de qualquer valor, exceto WMDM_SESSION_NONE. O mesmo tipo (ou combinação de tipos) deve ser especificado durante EndSession.

[in] pCtx

Ponteiro opcional para um buffer de contexto de sessão alocado pelo chamador para comunicação privada entre o aplicativo e o provedor de serviços. Os aplicativos que têm conhecimento do provedor de serviços subjacente podem usar esse buffer para passar dados específicos do contexto para ele. O Windows Media Gerenciador de Dispositivos não faz nada com esse contexto. O chamador é responsável por liberar esse buffer.

[in] dwSizeCtx

Tamanho do buffer de contexto, em bytes. Se o tamanho for 0, pCtx será ignorado. Se o tamanho for diferente de zero, pCtx deverá ser um ponteiro válido.

Retornar valor

O método retorna um HRESULT. Todos os métodos de interface no Windows Media Gerenciador de Dispositivos podem retornar qualquer uma das seguintes classes de códigos de erro:

  • Códigos de erro COM padrão
  • Códigos de erro do Windows convertidos em valores HRESULT
  • Códigos de erro do Windows Media Gerenciador de Dispositivos
Para obter uma lista abrangente de possíveis códigos de erro, consulte Códigos de erro.

Comentários

Agrupar várias operações em uma sessão não faz com que todas as ações sejam adiadas e executadas em um grupo; todas as ações (como uma chamada para Inserir) ainda serão executadas de forma síncrona, conforme chamado. Em vez disso, o uso de uma sessão permite que os componentes do Windows Media Gerenciador de Dispositivos (como o provedor de conteúdo seguro e o provedor de serviços) executem algumas das operações apenas uma vez por sessão, o que fornece melhorias de desempenho. Por exemplo, durante a transferência de arquivos para um dispositivo, o provedor de conteúdo seguro pode adquirir o certificado do dispositivo uma vez no início da sessão, em vez de uma vez para cada transferência de arquivo.

Os aplicativos podem chamar BeginSession em um objeto de dispositivo Gerenciador de Dispositivos do Windows Media antes de fazer um conjunto de operações e EndSession quando terminarem.

O aplicativo normalmente chama BeginSession durante várias transferências ou exclusões de arquivos. Em resposta a isso, o Windows Media Gerenciador de Dispositivos chama BeginSession ou EndSession no provedor de conteúdo seguro e no provedor de serviços. Em resposta, o provedor de conteúdo seguro e o provedor de serviços podem executar operações uma vez por sessão. Se a abertura da sessão falhar em qualquer um desses componentes, o Windows Media Gerenciador de Dispositivos retornará uma falha retornada pelo componente.

As sessões são implementadas por dispositivo. Sessões em dispositivos diferentes não interferem entre si.

As seguintes restrições se aplicam às sessões:

  1. Somente uma sessão pode estar ativa por vez para um dispositivo específico. Tentar abrir mais de uma sessão em um dispositivo resultará em um erro.
  2. Os tipos de sessão podem ser combinados. O mesmo conjunto de sinalizadores deve ser especificado durante BeginSession e EndSession. Portanto, não é possível terminar apenas parte da sessão.

    Por exemplo, se BeginSession for chamado com

    WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

    Em seguida , EndSession também deve ser chamado com

    WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

    Caso contrário, os Gerenciador de Dispositivos do Windows Media retornarão E_INVALIDARG.

  3. As sessões do Windows Media Gerenciador de Dispositivos são simplesmente um mecanismo de colchetes para otimizações e não têm implicações em relação ao bloqueio ou à propriedade do dispositivo. O provedor de serviços ou o driver de dispositivo de nível inferior ainda precisarão sincronizar o acesso ao dispositivo que pode resultar de diferentes aplicativos do Windows Media Gerenciador de Dispositivos.

Exemplos

O código C++ a seguir demonstra como usar uma sessão para agrupar uma chamada Insert3 em um dispositivo. O código executa um loop em vários arquivos armazenados em um vetor e os envia para o 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.");

Requisitos

Requisito Valor
Plataforma de Destino Windows
Cabeçalho mswmdm.h
Biblioteca Mssachlp.lib

Confira também

IWMDMDeviceSession Interface

IWMDMDeviceSession::EndSession

WMDM_SESSION_TYPE