Metodo IWMDMDeviceSession::BeginSession (mswmdm.h)

Articolo
03/15/2023

Il metodo BeginSession inizia una sessione del dispositivo.

Sintassi

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

Parametri

[in] type

Oggetto WMDM_SESSION_TYPE che descrive il tipo di sessione da iniziare. Si tratta di un OR bit per bit di qualsiasi valore ad eccezione di WMDM_SESSION_NONE. È necessario specificare lo stesso tipo (o combinazione di tipi) durante EndSession.

[in] pCtx

Puntatore facoltativo a un buffer del contesto di sessione allocato dal chiamante per la comunicazione privata tra l'applicazione e il provider di servizi. Le applicazioni con conoscenza del provider di servizi sottostanti possono usare questo buffer per passare dati specifici del contesto. Windows Media Gestione dispositivi non esegue alcuna operazione con questo contesto. Il chiamante è responsabile della liberazione di questo buffer.

[in] dwSizeCtx

Dimensioni del buffer di contesto, in byte. Se la dimensione è 0, pCtx viene ignorato. Se la dimensione è diversa da zero, pCtx deve essere un puntatore valido.

Valore restituito

Il metodo restituisce un valore HRESULT. Tutti i metodi di interfaccia in Windows Media Gestione dispositivi possono restituire una delle classi di codici di errore seguenti:

Codici di errore COM standard
Codici di errore di Windows convertiti in valori HRESULT
Codici di errore di Windows Media Gestione dispositivi

Per un elenco completo dei codici di errore possibili, vedere Codici di errore.

Commenti

La creazione di bundle di più operazioni in una sessione non comporta la posticipazione e l'esecuzione di tutte le azioni in un gruppo; tutte le azioni ,ad esempio una chiamata a Insert, verranno comunque eseguite in modo sincrono come chiamato. L'uso di una sessione consente invece ai componenti di Windows Media Gestione dispositivi (ad esempio il provider di contenuti protetti e il provider di servizi) di eseguire alcune delle operazioni una sola volta per sessione, che offre miglioramenti delle prestazioni. Ad esempio, durante il trasferimento di file in un dispositivo, il provider di contenuti protetti può acquisire il certificato del dispositivo una sola volta all'inizio della sessione anziché una volta per ogni trasferimento di file.

Le applicazioni possono chiamare BeginSession su un oggetto dispositivo windows Media Gestione dispositivi prima di eseguire un set di operazioni e EndSession al termine.

L'applicazione chiama in genere BeginSession durante più trasferimenti o eliminazioni di file. In risposta a questo, Windows Media Gestione dispositivi chiama BeginSession o EndSession sul provider di contenuti protetti e sul provider di servizi. In risposta, il provider di contenuti sicuri e il provider di servizi possono eseguire operazioni una sola volta per sessione. Se l'apertura della sessione non riesce in uno di questi componenti, Windows Media Gestione dispositivi restituisce un errore restituito dal componente.

Le sessioni vengono implementate per ogni dispositivo. Le sessioni su dispositivi diversi non interferiscono tra loro.

Le restrizioni seguenti si applicano alle sessioni:

Una sola sessione può essere attiva alla volta per un determinato dispositivo. Il tentativo di aprire più sessioni in un dispositivo genererà un errore.
I tipi di sessione possono essere combinati. Lo stesso set di flag deve essere specificato durante BeginSession e EndSession. Pertanto, non è possibile terminare solo parte della sessione.
Ad esempio, se BeginSession viene chiamato con

WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

È quindi necessario chiamare EndSession anche con

WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

In caso contrario, windows Media Gestione dispositivi restituirà E_INVALIDARG.
Le sessioni di windows Media Gestione dispositivi sono semplicemente un meccanismo di parentesi per le ottimizzazioni e non hanno implicazioni relative al blocco o alla proprietà del dispositivo. Il provider di servizi o il driver di dispositivo di livello inferiore dovrà comunque sincronizzare l'accesso al dispositivo che può derivare da diverse applicazioni di Windows Media Gestione dispositivi.

Esempio

Il codice C++ seguente illustra l'uso di una sessione per aggregare una chiamata Insert3 in un dispositivo. Il codice scorre un certo numero di file archiviati in un vettore e li invia 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.");