IWMDMDeviceSession::BeginSession-Methode (mswmdm.h)

Artikel
08/25/2023

Die BeginSession-Methode beginnt eine Gerätesitzung.

Syntax

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

Parameter

[in] type

Eine WMDM_SESSION_TYPE , die den Typ der zu beginnden Sitzung beschreibt. Dies ist ein bitweises OR aller Werte außer WMDM_SESSION_NONE. Derselbe Typ (oder eine Kombination aus Typen) muss während endSession angegeben werden.

[in] pCtx

Optionaler Zeiger auf einen vom Aufrufer zugewiesenen Sitzungskontextpuffer für die private Kommunikation zwischen der Anwendung und dem Dienstanbieter. Anwendungen, die über Kenntnisse des zugrunde liegenden Dienstanbieters verfügen, können diesen Puffer verwenden, um kontextspezifische Daten an ihn zu übergeben. Windows Media Geräte-Manager führt in diesem Kontext keine Aktionen aus. Der Aufrufer ist für die Freigabe dieses Puffers verantwortlich.

[in] dwSizeCtx

Größe des Kontextpuffers in Bytes. Wenn die Größe 0 ist, wird pCtx ignoriert. Wenn die Größe ungleich 0 ist, muss pCtx ein gültiger Zeiger sein.

Rückgabewert

Die Methode gibt ein HRESULT zurück. Alle Schnittstellenmethoden in Windows Media Geräte-Manager können eine der folgenden Klassen von Fehlercodes zurückgeben:

Standard-COM-Fehlercodes
In HRESULT-Werte konvertierte Windows-Fehlercodes
Windows Media Geräte-Manager Fehlercodes

Eine umfassende Liste möglicher Fehlercodes finden Sie unter Fehlercodes.

Hinweise

Das Bündeln mehrerer Vorgänge zu einer Sitzung führt nicht dazu, dass alle Aktionen verschoben und in einer Gruppe ausgeführt werden. Alle Aktionen (z. B. ein Aufruf von Insert) werden weiterhin synchron wie aufgerufen ausgeführt. Stattdessen ermöglicht die Verwendung einer Sitzung, dass Windows Media Geräte-Manager-Komponenten (z. B. anbieter für sichere Inhalte und Dienstanbieter) einige der Vorgänge nur einmal pro Sitzung ausführen können, was Leistungsverbesserungen bietet. Beispielsweise kann der Anbieter für sichere Inhalte während der Dateiübertragung auf ein Gerät das Gerätezertifikat einmal zu Beginn der Sitzung abrufen und nicht einmal für jede Dateiübertragung.

Anwendungen können BeginSession für ein Windows Media-Geräte-Manager-Geräteobjekt aufrufen, bevor sie eine Reihe von Vorgängen ausführen, und EndSession, wenn sie fertig sind.

Die Anwendung ruft BeginSession in der Regel während mehrerer Dateiübertragungen oder Löschungen auf. Als Reaktion darauf ruft Windows Media Geräte-Manager BeginSession oder EndSession für den anbieter für sichere Inhalte und den Dienstanbieter auf. Als Reaktion darauf können der sichere Inhaltsanbieter und der Dienstanbieter einmal pro Sitzung Vorgänge ausführen. Wenn das Öffnen der Sitzung für eine dieser Komponenten fehlschlägt, gibt Windows Media Geräte-Manager einen von der Komponente zurückgegebenen Fehler zurück.

Sitzungen werden auf Gerätebasis implementiert. Sitzungen auf verschiedenen Geräten stören sich nicht gegenseitig.

Die folgenden Einschränkungen gelten für Sitzungen:

Für ein bestimmtes Gerät kann jeweils nur eine Sitzung aktiv sein. Der Versuch, mehrere Sitzungen auf einem Gerät zu öffnen, führt zu einem Fehler.
Sitzungstypen können kombiniert werden. Derselbe Satz von Flags muss während BeginSession und EndSession angegeben werden. Daher ist es nicht möglich, nur einen Teil der Sitzung zu beenden.
Beispiel: Wenn BeginSession mit aufgerufen wird

WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

Dann sollte EndSession auch mit aufgerufen werden.

WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

Andernfalls gibt Windows Media Geräte-Manager E_INVALIDARG zurück.
Windows Media-Geräte-Manager-Sitzungen sind einfach ein Klammermechanismus für Optimierungen und haben keine Auswirkungen auf die Sperrung oder den Besitz des Geräts. Der Dienstanbieter oder der Gerätetreiber der niedrigeren Ebene muss weiterhin den Gerätezugriff synchronisieren, der sich aus verschiedenen Windows Media-Geräte-Manager-Anwendungen ergeben kann.

Beispiele

Der folgende C++-Code veranschaulicht die Verwendung einer Sitzung zum Bündeln eines Insert3-Aufrufs auf einem Gerät. Der Code durchläuft eine Reihe von Dateien, die in einem Vektor gespeichert sind, und sendet sie an das Gerät.


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