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

Article
08/25/2023

La méthode BeginSession démarre une session d’appareil.

Syntaxe

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

Paramètres

[in] type

Un WMDM_SESSION_TYPE décrivant le type de session à commencer. Il s’agit d’un OR au niveau du bit de toutes les valeurs, à l’exception de WMDM_SESSION_NONE. Le même type (ou combinaison de types) doit être spécifié pendant EndSession.

[in] pCtx

Pointeur facultatif vers une mémoire tampon de contexte de session allouée par l’appelant pour la communication privée entre l’application et le fournisseur de services. Les applications qui connaissent le fournisseur de services sous-jacent peuvent utiliser cette mémoire tampon pour lui transmettre des données spécifiques au contexte. Windows Media Gestionnaire de périphériques ne fait rien avec ce contexte. L’appelant est responsable de libérer cette mémoire tampon.

[in] dwSizeCtx

Taille de la mémoire tampon de contexte, en octets. Si la taille est 0, pCtx est ignoré. Si la taille n’est pas égale à zéro, pCtx doit être un pointeur valide.

Valeur retournée

Cette méthode retourne un code HRESULT. Toutes les méthodes d’interface dans Windows Media Gestionnaire de périphériques peuvent retourner l’une des classes de codes d’erreur suivantes :

Codes d’erreur COM standard
Codes d’erreur Windows convertis en valeurs HRESULT
Codes d’erreur Gestionnaire de périphériques Windows Media

Pour obtenir une liste complète des codes d’erreur possibles, consultez Codes d’erreur.

Remarques

Le regroupement de plusieurs opérations dans une session n’entraîne pas le report et l’exécution de toutes les actions dans un groupe ; toutes les actions (telles qu’un appel à Insérer) seront toujours effectuées de manière synchrone, comme appelées. Au lieu de cela, l’utilisation d’une session permet aux composants Windows Media Gestionnaire de périphériques (tels que le fournisseur de contenu sécurisé et le fournisseur de services) d’effectuer certaines opérations une seule fois par session, ce qui permet d’améliorer les performances. Par exemple, lors du transfert de fichiers vers un appareil, le fournisseur de contenu sécurisé peut acquérir le certificat d’appareil une fois au début de la session au lieu d’une fois pour chaque transfert de fichiers.

Les applications peuvent appeler BeginSession sur un objet d’appareil Windows Media Gestionnaire de périphériques avant d’effectuer un ensemble d’opérations et EndSession lorsqu’elles sont terminées.

L’application appelle généralement BeginSession lors de plusieurs transferts ou suppressions de fichiers. En réponse à cela, Windows Media Gestionnaire de périphériques appelle BeginSession ou EndSession sur le fournisseur de contenu sécurisé et le fournisseur de services. En réponse, le fournisseur de contenu sécurisé et le fournisseur de services peuvent effectuer des opérations une fois par session. Si l’ouverture de la session échoue sur l’un de ces composants, Windows Media Gestionnaire de périphériques retourne un échec retourné par le composant.

Les sessions sont implémentées sur une base par appareil. Les sessions sur différents appareils n’interfèrent pas entre elles.

Les restrictions suivantes s’appliquent aux sessions :

Une seule session peut être active à la fois pour un appareil particulier. La tentative d’ouverture de plusieurs sessions sur un appareil entraîne une erreur.
Les types de session peuvent être combinés. Le même ensemble d’indicateurs doit être spécifié pendant BeginSession et EndSession. Par conséquent, il n’est pas possible de mettre fin uniquement à une partie de la session.
Par exemple, si BeginSession est appelé avec

WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

Ensuite , EndSession doit également être appelé avec

WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

Sinon, le Gestionnaire de périphériques Windows Media retourne E_INVALIDARG.
Les sessions Windows Media Gestionnaire de périphériques sont simplement un mécanisme de crochetage pour les optimisations et n’ont aucune incidence sur le verrouillage ou la propriété de l’appareil. Le fournisseur de services ou le pilote de périphérique de niveau inférieur devront toujours synchroniser l’accès aux appareils qui peut résulter de différentes applications Windows Media Gestionnaire de périphériques.

Exemples

Le code C++ suivant illustre l’utilisation d’une session pour regrouper un appel Insert3 sur un appareil. Le code effectue une boucle dans un certain nombre de fichiers stockés dans un vecteur et les envoie à l’appareil.


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