Package com.google.android.exoplayer2.drm

## Class DefaultDrmSessionManager

- java.lang.Object
- - com.google.android.exoplayer2.drm.DefaultDrmSessionManager

- All Implemented Interfaces:
    `DrmSessionManager`

      @RequiresApi(18)
      public class DefaultDrmSessionManager
      extends Object
      implements DrmSessionManager

  A `DrmSessionManager` that supports playbacks using `ExoMediaDrm`.

  This implementation supports pre-acquisition of sessions using `preacquireSession(Looper, DrmSessionEventListener.EventDispatcher, Format)`.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class | Description
    --- | --- | ---
    `static class` | `DefaultDrmSessionManager.Builder` | Builder for `DefaultDrmSessionManager` instances.
    `static class` | `DefaultDrmSessionManager.MissingSchemeDataException` | Signals that the `Format.drmInitData` passed to `acquireSession(android.os.Looper, com.google.android.exoplayer2.drm.DrmSessionEventListener.EventDispatcher, com.google.android.exoplayer2.Format)` does not contain scheme data for the required UUID.
    `static interface` | `DefaultDrmSessionManager.Mode` | Determines the action to be done after a session acquired.

    - ### Nested classes/interfaces inherited from interface com.google.android.exoplayer2.drm.DrmSessionManager

      `DrmSessionManager.DrmSessionReference`

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static long` | `DEFAULT_SESSION_KEEPALIVE_MS` | Default value for `DefaultDrmSessionManager.Builder.setSessionKeepaliveMs(long)`.
    `static int` | `INITIAL_DRM_REQUEST_RETRY_COUNT` | Number of times to retry for initial provisioning and key request for reporting error.
    `static int` | `MODE_DOWNLOAD` | Downloads an offline license or renews an existing one.
    `static int` | `MODE_PLAYBACK` | Loads and refreshes (if necessary) a license for playback.
    `static int` | `MODE_QUERY` | Restores an offline license to allow its status to be queried.
    `static int` | `MODE_RELEASE` | Releases an existing offline license.
    `static String` | `PLAYREADY_CUSTOM_DATA_KEY` | A key for specifying PlayReady custom data in the key request parameters passed to `DefaultDrmSessionManager.Builder.setKeyRequestParameters(Map)`.

    - ### Fields inherited from interface com.google.android.exoplayer2.drm.DrmSessionManager

      `DRM_UNSUPPORTED, DUMMY`

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `DefaultDrmSessionManager​(UUID uuid, ExoMediaDrm exoMediaDrm, MediaDrmCallback callback, HashMap<String,​String> keyRequestParameters)` | Deprecated. Use `DefaultDrmSessionManager.Builder` instead.
    `DefaultDrmSessionManager​(UUID uuid, ExoMediaDrm exoMediaDrm, MediaDrmCallback callback, HashMap<String,​String> keyRequestParameters, boolean multiSession)` | Deprecated. Use `DefaultDrmSessionManager.Builder` instead.
    `DefaultDrmSessionManager​(UUID uuid, ExoMediaDrm exoMediaDrm, MediaDrmCallback callback, HashMap<String,​String> keyRequestParameters, boolean multiSession, int initialDrmRequestRetryCount)` | Deprecated. Use `DefaultDrmSessionManager.Builder` instead.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `DrmSession` | `acquireSession​(Looper playbackLooper, DrmSessionEventListener.EventDispatcher eventDispatcher, Format format)` | Returns a `DrmSession` for the specified `Format`, with an incremented reference count.
    `Class<? extends ExoMediaCrypto>` | `getExoMediaCryptoType​(Format format)` | Returns the `ExoMediaCrypto` type associated to sessions acquired for the given `Format`.
    `DrmSessionManager.DrmSessionReference` | `preacquireSession​(Looper playbackLooper, DrmSessionEventListener.EventDispatcher eventDispatcher, Format format)` | Pre-acquires a DRM session for the specified `Format`.
    `void` | `prepare()` | Acquires any required resources.
    `void` | `release()` | Releases any acquired resources.
    `void` | `setMode​(int mode, byte[] offlineLicenseKeySetId)` | Sets the mode, which determines the role of sessions acquired from the instance.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### PLAYREADY_CUSTOM_DATA_KEY

          public static final String PLAYREADY_CUSTOM_DATA_KEY

      A key for specifying PlayReady custom data in the key request parameters passed to `DefaultDrmSessionManager.Builder.setKeyRequestParameters(Map)`.
      See Also:
        Constant Field Values

    - #### MODE_PLAYBACK

          public static final int MODE_PLAYBACK

      Loads and refreshes (if necessary) a license for playback. Supports streaming and offline licenses.
      See Also:
        Constant Field Values

    - #### MODE_QUERY

          public static final int MODE_QUERY

      Restores an offline license to allow its status to be queried.
      See Also:
        Constant Field Values

    - #### MODE_DOWNLOAD

          public static final int MODE_DOWNLOAD

      Downloads an offline license or renews an existing one.
      See Also:
        Constant Field Values

    - #### MODE_RELEASE

          public static final int MODE_RELEASE

      Releases an existing offline license.
      See Also:
        Constant Field Values

    - #### INITIAL_DRM_REQUEST_RETRY_COUNT

          public static final int INITIAL_DRM_REQUEST_RETRY_COUNT

      Number of times to retry for initial provisioning and key request for reporting error.
      See Also:
        Constant Field Values

    - #### DEFAULT_SESSION_KEEPALIVE_MS

          public static final long DEFAULT_SESSION_KEEPALIVE_MS

      Default value for `DefaultDrmSessionManager.Builder.setSessionKeepaliveMs(long)`.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### DefaultDrmSessionManager

          @Deprecated
          public DefaultDrmSessionManager​(UUID uuid,
                                          ExoMediaDrm exoMediaDrm,
                                          MediaDrmCallback callback,
                                          @Nullable
                                          HashMap<String,​String> keyRequestParameters)

      Deprecated.
      Use `DefaultDrmSessionManager.Builder` instead.
      Parameters:
        `uuid` - The UUID of the drm scheme.
        `exoMediaDrm` - An underlying `ExoMediaDrm` for use by the manager.
        `callback` - Performs key and provisioning requests.
        `keyRequestParameters` - An optional map of parameters to pass as the last argument to `ExoMediaDrm.getKeyRequest(byte[], List, int, HashMap)`. May be null.

    - #### DefaultDrmSessionManager

          @Deprecated
          public DefaultDrmSessionManager​(UUID uuid,
                                          ExoMediaDrm exoMediaDrm,
                                          MediaDrmCallback callback,
                                          @Nullable
                                          HashMap<String,​String> keyRequestParameters,
                                          boolean multiSession)

      Deprecated.
      Use `DefaultDrmSessionManager.Builder` instead.
      Parameters:
        `uuid` - The UUID of the drm scheme.
        `exoMediaDrm` - An underlying `ExoMediaDrm` for use by the manager.
        `callback` - Performs key and provisioning requests.
        `keyRequestParameters` - An optional map of parameters to pass as the last argument to `ExoMediaDrm.getKeyRequest(byte[], List, int, HashMap)`. May be null.
        `multiSession` - A boolean that specify whether multiple key session support is enabled. Default is false.

    - #### DefaultDrmSessionManager

          @Deprecated
          public DefaultDrmSessionManager​(UUID uuid,
                                          ExoMediaDrm exoMediaDrm,
                                          MediaDrmCallback callback,
                                          @Nullable
                                          HashMap<String,​String> keyRequestParameters,
                                          boolean multiSession,
                                          int initialDrmRequestRetryCount)

      Deprecated.
      Use `DefaultDrmSessionManager.Builder` instead.
      Parameters:
        `uuid` - The UUID of the drm scheme.
        `exoMediaDrm` - An underlying `ExoMediaDrm` for use by the manager.
        `callback` - Performs key and provisioning requests.
        `keyRequestParameters` - An optional map of parameters to pass as the last argument to `ExoMediaDrm.getKeyRequest(byte[], List, int, HashMap)`. May be null.
        `multiSession` - A boolean that specify whether multiple key session support is enabled. Default is false.
        `initialDrmRequestRetryCount` - The number of times to retry for initial provisioning and key request before reporting error.

  - ### Method Detail

    - #### setMode

          public void setMode​(@Mode
                              int mode,
                              @Nullable
                              byte[] offlineLicenseKeySetId)

      Sets the mode, which determines the role of sessions acquired from the instance. This must be called before `acquireSession(Looper, DrmSessionEventListener.EventDispatcher, Format)` is called.

      By default, the mode is `MODE_PLAYBACK` and a streaming license is requested when required.

      `mode` must be one of these:

      - `MODE_PLAYBACK`: If `offlineLicenseKeySetId` is null then a streaming license is requested. Otherwise, the offline license is restored.
      - `MODE_QUERY`: `offlineLicenseKeySetId` cannot be null. The offline license is restored to allow its status to be queried.
      - `MODE_DOWNLOAD`: If `offlineLicenseKeySetId` is null then an offline license is requested. Otherwise, the offline license is renewed.
      - `MODE_RELEASE`: `offlineLicenseKeySetId` cannot be null. The offline license is released.
      Parameters:
        `mode` - The mode to be set.
        `offlineLicenseKeySetId` - The key set id of the license to be used with the given mode.

    - #### prepare

          public final void prepare()

      Description copied from interface: `DrmSessionManager`
      Acquires any required resources.

      `DrmSessionManager.release()` must be called to ensure the acquired resources are released. After releasing, an instance may be re-prepared.

      Specified by:
        `prepare` in interface `DrmSessionManager`

    - #### release

          public final void release()

      Description copied from interface: `DrmSessionManager`
      Releases any acquired resources.
      Specified by:
        `release` in interface `DrmSessionManager`

    - #### preacquireSession

          public DrmSessionManager.DrmSessionReference preacquireSession​(Looper playbackLooper,
                                                                         @Nullable
                                                                         DrmSessionEventListener.EventDispatcher eventDispatcher,
                                                                         Format format)

      Description copied from interface: `DrmSessionManager`
      Pre-acquires a DRM session for the specified `Format`.

      This notifies the manager that a subsequent call to `DrmSessionManager.acquireSession(Looper, DrmSessionEventListener.EventDispatcher, Format)` with the same `Format` is likely, allowing a manager that supports pre-acquisition to get the required `DrmSession` ready in the background.

      The caller must call `DrmSessionManager.DrmSessionReference.release()` on the returned instance when they no longer require the pre-acquisition (i.e. they know they won't be making a matching call to `DrmSessionManager.acquireSession(Looper, DrmSessionEventListener.EventDispatcher, Format)` in the near future).

      This manager may silently release the underlying session in order to allow another operation to complete. This will result in a subsequent call to `DrmSessionManager.acquireSession(Looper, DrmSessionEventListener.EventDispatcher, Format)` re-initializing a new session, including repeating key loads and other async initialization steps.

      The caller must separately call `DrmSessionManager.acquireSession(Looper, DrmSessionEventListener.EventDispatcher, Format)` in order to obtain a session suitable for playback. The pre-acquired `DrmSessionManager.DrmSessionReference` and full `DrmSession` instances are distinct. The caller must release both, and can release the `DrmSessionManager.DrmSessionReference` before the `DrmSession` without affecting playback.

      This can be called from any thread.

      Implementations that do not support pre-acquisition always return an empty `DrmSessionManager.DrmSessionReference` instance.

      Specified by:
        `preacquireSession` in interface `DrmSessionManager`
      Parameters:
        `playbackLooper` - The looper associated with the media playback thread.
        `eventDispatcher` - The `DrmSessionEventListener.EventDispatcher` used to distribute events, and passed on to `DrmSession.acquire(DrmSessionEventListener.EventDispatcher)`.
        `format` - The `Format` for which to pre-acquire a `DrmSession`.
      Returns:
        A releaser for the pre-acquired session. Guaranteed to be non-null even if the matching `DrmSessionManager.acquireSession(Looper, DrmSessionEventListener.EventDispatcher, Format)` would return null.

    - #### acquireSession

          @Nullable
          public DrmSession acquireSession​(Looper playbackLooper,
                                           @Nullable
                                           DrmSessionEventListener.EventDispatcher eventDispatcher,
                                           Format format)

      Description copied from interface: `DrmSessionManager`
      Returns a `DrmSession` for the specified `Format`, with an incremented reference count. May return null if the `Format.drmInitData` is null and the DRM session manager is not configured to attach a `DrmSession` to clear content. When the caller no longer needs to use a returned `DrmSession`, it must call `DrmSession.release(DrmSessionEventListener.EventDispatcher)` to decrement the reference count.

      If the provided `Format` contains a null `Format.drmInitData`, the returned `DrmSession` (if not null) will be a placeholder session which does not execute key requests, and cannot be used to handle encrypted content. However, a placeholder session may be used to configure secure decoders for playback of clear content periods, which can reduce the cost of transitioning between clear and encrypted content.

      Specified by:
        `acquireSession` in interface `DrmSessionManager`
      Parameters:
        `playbackLooper` - The looper associated with the media playback thread.
        `eventDispatcher` - The `DrmSessionEventListener.EventDispatcher` used to distribute events, and passed on to `DrmSession.acquire(DrmSessionEventListener.EventDispatcher)`.
        `format` - The `Format` for which to acquire a `DrmSession`.
      Returns:
        The DRM session. May be null if the given `Format.drmInitData` is null.

    - #### getExoMediaCryptoType

          @Nullable
          public Class<? extends ExoMediaCrypto> getExoMediaCryptoType​(Format format)

      Description copied from interface: `DrmSessionManager`
      Returns the `ExoMediaCrypto` type associated to sessions acquired for the given `Format`. Returns the `UnsupportedMediaCrypto` type if this DRM session manager does not support any of the DRM schemes defined in the given `Format`. Returns null if `Format.drmInitData` is null and `DrmSessionManager.acquireSession(android.os.Looper, com.google.android.exoplayer2.drm.DrmSessionEventListener.EventDispatcher, com.google.android.exoplayer2.Format)` would return null for the given `Format`.
      Specified by:
        `getExoMediaCryptoType` in interface `DrmSessionManager`
      Parameters:
        `format` - The `Format` for which to return the `ExoMediaCrypto` type.
      Returns:
        The `ExoMediaCrypto` type associated to sessions acquired using the given `Format`, or `UnsupportedMediaCrypto` if this DRM session manager does not support any of the DRM schemes defined in the given `Format`. May be null if `Format.drmInitData` is null and `DrmSessionManager.acquireSession(android.os.Looper, com.google.android.exoplayer2.drm.DrmSessionEventListener.EventDispatcher, com.google.android.exoplayer2.Format)` would return null for the given `Format`.