Package com.google.android.exoplayer2.drm

## Interface DrmSessionManager

- All Known Implementing Classes:
    `DefaultDrmSessionManager`

      public interface DrmSessionManager

  Manages a DRM session.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static interface` | `DrmSessionManager.DrmSessionReference` | Represents a single reference count of a `DrmSession`, while deliberately not giving access to the underlying session.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static DrmSessionManager` | `DRM_UNSUPPORTED` | An instance that supports no DRM schemes.
    `static DrmSessionManager` | `DUMMY` | Deprecated. Use `DRM_UNSUPPORTED`.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Default Methods Deprecated 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.
    `static DrmSessionManager` | `getDummyDrmSessionManager()` | Deprecated. Use `DRM_UNSUPPORTED`.
    `Class<? extends ExoMediaCrypto>` | `getExoMediaCryptoType​(Format format)` | Returns the `ExoMediaCrypto` type associated to sessions acquired for the given `Format`.
    `default DrmSessionManager.DrmSessionReference` | `preacquireSession​(Looper playbackLooper, DrmSessionEventListener.EventDispatcher eventDispatcher, Format format)` | Pre-acquires a DRM session for the specified `Format`.
    `default void` | `prepare()` | Acquires any required resources.
    `default void` | `release()` | Releases any acquired resources.

- - ### Field Detail

    - #### DRM_UNSUPPORTED

          static final DrmSessionManager DRM_UNSUPPORTED

      An instance that supports no DRM schemes.

    - #### DUMMY

          @Deprecated
          static final DrmSessionManager DUMMY

      Deprecated.
      Use `DRM_UNSUPPORTED`.
      An instance that supports no DRM schemes.

  - ### Method Detail

    - #### getDummyDrmSessionManager

          @Deprecated
          static DrmSessionManager getDummyDrmSessionManager()

      Deprecated.
      Use `DRM_UNSUPPORTED`.
      Returns `DRM_UNSUPPORTED`.

    - #### prepare

          default void prepare()

      Acquires any required resources.

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

    - #### release

          default void release()

      Releases any acquired resources.

    - #### preacquireSession

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

      Pre-acquires a DRM session for the specified `Format`.

      This notifies the manager that a subsequent call to `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 `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 `acquireSession(Looper, DrmSessionEventListener.EventDispatcher, Format)` re-initializing a new session, including repeating key loads and other async initialization steps.

      The caller must separately call `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.

      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 `acquireSession(Looper, DrmSessionEventListener.EventDispatcher, Format)` would return null.

    - #### acquireSession

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

      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.

      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
          Class<? extends ExoMediaCrypto> getExoMediaCryptoType​(Format format)

      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 `acquireSession(android.os.Looper, com.google.android.exoplayer2.drm.DrmSessionEventListener.EventDispatcher, com.google.android.exoplayer2.Format)` would return null for the given `Format`.
      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 `acquireSession(android.os.Looper, com.google.android.exoplayer2.drm.DrmSessionEventListener.EventDispatcher, com.google.android.exoplayer2.Format)` would return null for the given `Format`.