IWMDMDeviceSession::BeginSession

The BeginSession method begins a device session.

Syntax

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

Parameters

type

[in]  Type of session to begin, composed of any logical combination of the following defined bit fields.

The same type (or combination of types) must be specified during EndSession.

pCtx

[in]  Pointer to the session context buffer for private communication between the application and the service provider. Windows Media Device Manager does not do anything with this context except validate it. It can be NULL if dwSizeCtx is 0.

dwSizeCtx

[in]  Size of the context buffer, in bytes. If the size is 0, pCtx is ignored. If the size is non-zero, pCtx must be a valid pointer.

Return Values

The method returns an HRESULT. All the interface methods in Windows Media Device Manager and service provider can return any of the following classes of error codes:

• Standard COM error codes
• Windows error codes converted to HRESULT values
• Windows Media Device Manager error codes

For a complete list of possible error codes, see Error Codes.

Possible values include, but are not limited to, those in the following table.

Remarks

Applications can call BeginSession on a Windows Media Device Manager device object before doing a set of operations and EndSession when they are done. This allows Windows Media Device Manager components (secure content provider and service provider) to perform some of the operations only once per session, which provides performance improvements. For example, during file transfer to a device, the secure content provider can acquire the device certificate once at the beginning of the session instead of once for every file transfer.

The application typically calls BeginSession during multiple file transfers or deletions. In response to that, Windows Media Device Manager calls BeginSession or EndSession on the secure content provider and the service provider. In response, the secure content provider and the service provider can perform once-per-session operations. If opening the session fails on any of these components, Windows Media Device Manager attempts to undo all the sessions and returns a failure returned by the component.

Sessions are implemented on a per-device basis. Sessions on different devices do not interfere with each other.

Following are the restrictions on sessions:

1. Only one session can be active at a time for a particular device. Attempting to open more than one session on a device will result in an error.

2. Session types can be combined. The same set of flags must be specified during BeginSession and EndSession. Therefore, it is not possible to end only part of the session.

   For example, if BeginSession is called with

   WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

   Then EndSession should also be called with

   WMDM_SESSION_TRANSFER_TO_DEVICE | WMDM_SESSION_DELETE

   Otherwise Windows Media Device Manager will return E_INVALIDARG.

3. Windows Media Device Manager sessions are simply a bracketing mechanism for optimizations and do not have any implications regarding locking or ownership of the device. Service provider or the lower level device driver will still need to synchronize device access that may result from different Windows Media Device Manager applications.

Applications having knowledge of the underlying service provider can use the context buffer to pass context-specific data to it.

Requirements

Header: Defined in wmdm.idl.

Library: mssachlp.lib

See Also

• IWMDMDeviceSession Interface
• IWMDMDeviceSession::EndSession
• WMDM_SESSION_TYPE