Package com.google.android.exoplayer2.drm

## Interface ExoMediaDrm

- All Known Implementing Classes:
    `DummyExoMediaDrm`, `FakeExoMediaDrm`, `FrameworkMediaDrm`

      public interface ExoMediaDrm

  Used to obtain keys for decrypting protected media streams.

  ## Reference counting

  Access to an instance is managed by reference counting, where `acquire()` increments the reference count and `release()` decrements it. When the reference count drops to 0 underlying resources are released, and the instance cannot be re-used.

  Each new instance has an initial reference count of 1. Hence application code that creates a new instance does not normally need to call `acquire()`, and must call `release()` when the instance is no longer required.

  See Also:
    `MediaDrm`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface | Description
    --- | --- | ---
    `static class` | `ExoMediaDrm.AppManagedProvider` | Provides an `ExoMediaDrm` instance owned by the app.
    `static class` | `ExoMediaDrm.KeyRequest` | Contains data used to request keys from a license server.
    `static class` | `ExoMediaDrm.KeyStatus` | Defines the status of a key.
    `static interface` | `ExoMediaDrm.OnEventListener` | Called when a DRM event occurs.
    `static interface` | `ExoMediaDrm.OnExpirationUpdateListener` | Called when a session expiration update occurs.
    `static interface` | `ExoMediaDrm.OnKeyStatusChangeListener` | Called when the keys in a DRM session change state.
    `static interface` | `ExoMediaDrm.Provider` | Provider for `ExoMediaDrm` instances.
    `static class` | `ExoMediaDrm.ProvisionRequest` | Contains data to request a certificate from a provisioning server.

  - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static int` | `EVENT_KEY_EXPIRED` | Event indicating that keys have expired, and are no longer usable.
    `static int` | `EVENT_KEY_REQUIRED` | Event indicating that keys need to be requested from the license server.
    `static int` | `EVENT_PROVISION_REQUIRED` | Event indicating that a certificate needs to be requested from the provisioning server.
    `static int` | `KEY_TYPE_OFFLINE` | Key request type for keys that will be used for offline use.
    `static int` | `KEY_TYPE_RELEASE` | Key request type indicating that saved offline keys should be released.
    `static int` | `KEY_TYPE_STREAMING` | Key request type for keys that will be used for online use.

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `void` | `acquire()` | Increments the reference count.
    `void` | `closeSession​(byte[] sessionId)` | Closes a DRM session.
    `ExoMediaCrypto` | `createMediaCrypto​(byte[] sessionId)` | Creates an `ExoMediaCrypto` for a given session.
    `Class<? extends ExoMediaCrypto>` | `getExoMediaCryptoType()` | Returns the `ExoMediaCrypto` type created by `createMediaCrypto(byte[])`.
    `ExoMediaDrm.KeyRequest` | `getKeyRequest​(byte[] scope, List<DrmInitData.SchemeData> schemeDatas, int keyType, HashMap<String,​String> optionalParameters)` | Generates a key request.
    `PersistableBundle` | `getMetrics()` | Returns metrics data for this ExoMediaDrm instance, or `null` if metrics are unavailable.
    `byte[]` | `getPropertyByteArray​(String propertyName)` | Returns the value of a byte array property.
    `String` | `getPropertyString​(String propertyName)` | Returns the value of a string property.
    `ExoMediaDrm.ProvisionRequest` | `getProvisionRequest()` | Generates a provisioning request.
    `byte[]` | `openSession()` | Opens a new DRM session.
    `byte[]` | `provideKeyResponse​(byte[] scope, byte[] response)` | Provides a key response for the last request to be generated using `getKeyRequest(byte[], java.util.List<com.google.android.exoplayer2.drm.DrmInitData.SchemeData>, int, java.util.HashMap<java.lang.String, java.lang.String>)`.
    `void` | `provideProvisionResponse​(byte[] response)` | Provides a provisioning response for the last request to be generated using `getProvisionRequest()`.
    `Map<String,​String>` | `queryKeyStatus​(byte[] sessionId)` | Returns the key status for a given session, as {name, value} pairs.
    `void` | `release()` | Decrements the reference count.
    `void` | `restoreKeys​(byte[] sessionId, byte[] keySetId)` | Restores persisted offline keys into a session.
    `void` | `setOnEventListener​(ExoMediaDrm.OnEventListener listener)` | Sets the listener for DRM events.
    `void` | `setOnExpirationUpdateListener​(ExoMediaDrm.OnExpirationUpdateListener listener)` | Sets the listener for session expiration events.
    `void` | `setOnKeyStatusChangeListener​(ExoMediaDrm.OnKeyStatusChangeListener listener)` | Sets the listener for key status change events.
    `void` | `setPropertyByteArray​(String propertyName, byte[] value)` | Sets the value of a byte array property.
    `void` | `setPropertyString​(String propertyName, String value)` | Sets the value of a string property.

- - ### Field Detail

    - #### EVENT_KEY_REQUIRED

          static final int EVENT_KEY_REQUIRED

      Event indicating that keys need to be requested from the license server.
      See Also:
        Constant Field Values

    - #### EVENT_KEY_EXPIRED

          static final int EVENT_KEY_EXPIRED

      Event indicating that keys have expired, and are no longer usable.
      See Also:
        Constant Field Values

    - #### EVENT_PROVISION_REQUIRED

          static final int EVENT_PROVISION_REQUIRED

      Event indicating that a certificate needs to be requested from the provisioning server.
      See Also:
        Constant Field Values

    - #### KEY_TYPE_STREAMING

          static final int KEY_TYPE_STREAMING

      Key request type for keys that will be used for online use. Streaming keys will not be saved to the device for subsequent use when the device is not connected to a network.
      See Also:
        Constant Field Values

    - #### KEY_TYPE_OFFLINE

          static final int KEY_TYPE_OFFLINE

      Key request type for keys that will be used for offline use. They will be saved to the device for subsequent use when the device is not connected to a network.
      See Also:
        Constant Field Values

    - #### KEY_TYPE_RELEASE

          static final int KEY_TYPE_RELEASE

      Key request type indicating that saved offline keys should be released.
      See Also:
        Constant Field Values

  - ### Method Detail

    - #### setOnEventListener

          void setOnEventListener​(@Nullable
                                  ExoMediaDrm.OnEventListener listener)

      Sets the listener for DRM events.

      This is an optional method, and some implementations may only support it on certain Android API levels.

      Parameters:
        `listener` - The listener to receive events, or `null` to stop receiving events.
      Throws:
        `UnsupportedOperationException` - if the implementation doesn't support this method.
      See Also:
        `MediaDrm.setOnEventListener(MediaDrm.OnEventListener)`

    - #### setOnKeyStatusChangeListener

          void setOnKeyStatusChangeListener​(@Nullable
                                            ExoMediaDrm.OnKeyStatusChangeListener listener)

      Sets the listener for key status change events.

      This is an optional method, and some implementations may only support it on certain Android API levels.

      Parameters:
        `listener` - The listener to receive events, or `null` to stop receiving events.
      Throws:
        `UnsupportedOperationException` - if the implementation doesn't support this method.
      See Also:
        `MediaDrm.setOnKeyStatusChangeListener(MediaDrm.OnKeyStatusChangeListener, Handler)`

    - #### setOnExpirationUpdateListener

          void setOnExpirationUpdateListener​(@Nullable
                                             ExoMediaDrm.OnExpirationUpdateListener listener)

      Sets the listener for session expiration events.

      This is an optional method, and some implementations may only support it on certain Android API levels.

      Parameters:
        `listener` - The listener to receive events, or `null` to stop receiving events.
      Throws:
        `UnsupportedOperationException` - if the implementation doesn't support this method.
      See Also:
        `MediaDrm.setOnExpirationUpdateListener(MediaDrm.OnExpirationUpdateListener, Handler)`

    - #### openSession

          byte[] openSession()
                      throws MediaDrmException

      Opens a new DRM session. A session ID is returned.
      Returns:
        The session ID.
      Throws:
        `NotProvisionedException` - If provisioning is needed.
        `ResourceBusyException` - If required resources are in use.
        `MediaDrmException` - If the session could not be opened.

    - #### closeSession

          void closeSession​(byte[] sessionId)

      Closes a DRM session.
      Parameters:
        `sessionId` - The ID of the session to close.

    - #### getKeyRequest

          ExoMediaDrm.KeyRequest getKeyRequest​(byte[] scope,
                                               @Nullable
                                               List<DrmInitData.SchemeData> schemeDatas,
                                               int keyType,
                                               @Nullable
                                               HashMap<String,​String> optionalParameters)
                                        throws NotProvisionedException

      Generates a key request.
      Parameters:
        `scope` - If `keyType` is `KEY_TYPE_STREAMING` or `KEY_TYPE_OFFLINE`, the ID of the session that the keys will be provided to. If `keyType` is `KEY_TYPE_RELEASE`, the `keySetId` of the keys to release.
        `schemeDatas` - If key type is `KEY_TYPE_STREAMING` or `KEY_TYPE_OFFLINE`, a list of `DrmInitData.SchemeData` instances extracted from the media. Null otherwise.
        `keyType` - The type of the request. Either `KEY_TYPE_STREAMING` to acquire keys for streaming, `KEY_TYPE_OFFLINE` to acquire keys for offline usage, or `KEY_TYPE_RELEASE` to release acquired keys. Releasing keys invalidates them for all sessions.
        `optionalParameters` - Are included in the key request message to allow a client application to provide additional message parameters to the server. This may be `null` if no additional parameters are to be sent.
      Returns:
        The generated key request.
      Throws:
        `NotProvisionedException`
      See Also:
        `MediaDrm.getKeyRequest(byte[], byte[], String, int, HashMap)`

    - #### provideKeyResponse

          @Nullable
          byte[] provideKeyResponse​(byte[] scope,
                                    byte[] response)
                             throws NotProvisionedException,
                                    DeniedByServerException

      Provides a key response for the last request to be generated using `getKeyRequest(byte[], java.util.List<com.google.android.exoplayer2.drm.DrmInitData.SchemeData>, int, java.util.HashMap<java.lang.String, java.lang.String>)`.
      Parameters:
        `scope` - If the request had type `KEY_TYPE_STREAMING` or `KEY_TYPE_OFFLINE`, the ID of the session to provide the keys to. If `keyType` is `KEY_TYPE_RELEASE`, the `keySetId` of the keys being released.
        `response` - The response data from the server.
      Returns:
        If the request had type `KEY_TYPE_OFFLINE`, the `keySetId` for the offline keys. An empty byte array or `null` may be returned for other cases.
      Throws:
        `NotProvisionedException` - If the response indicates that provisioning is needed.
        `DeniedByServerException` - If the response indicates that the server rejected the request.

    - #### getProvisionRequest

          ExoMediaDrm.ProvisionRequest getProvisionRequest()

      Generates a provisioning request.
      Returns:
        The generated provisioning request.

    - #### provideProvisionResponse

          void provideProvisionResponse​(byte[] response)
                                 throws DeniedByServerException

      Provides a provisioning response for the last request to be generated using `getProvisionRequest()`.
      Parameters:
        `response` - The response data from the server.
      Throws:
        `DeniedByServerException` - If the response indicates that the server rejected the request.

    - #### queryKeyStatus

          Map<String,​String> queryKeyStatus​(byte[] sessionId)

      Returns the key status for a given session, as {name, value} pairs. Since DRM license policies vary by vendor, the returned entries depend on the DRM plugin being used. Refer to your DRM provider's documentation for more information.
      Parameters:
        `sessionId` - The ID of the session being queried.
      Returns:
        The key status for the session.

    - #### acquire

          void acquire()

      Increments the reference count. When the caller no longer needs to use the instance, it must call `release()` to decrement the reference count.

      A new instance will have an initial reference count of 1, and therefore it is not normally necessary for application code to call this method.

    - #### release

          void release()

      Decrements the reference count. If the reference count drops to 0 underlying resources are released, and the instance cannot be re-used.

    - #### restoreKeys

          void restoreKeys​(byte[] sessionId,
                           byte[] keySetId)

      Restores persisted offline keys into a session.
      Parameters:
        `sessionId` - The ID of the session into which the keys will be restored.
        `keySetId` - The `keySetId` of the keys to restore, as provided by the call to `provideKeyResponse(byte[], byte[])` that persisted them.

    - #### getMetrics

          @Nullable
          PersistableBundle getMetrics()

      Returns metrics data for this ExoMediaDrm instance, or `null` if metrics are unavailable.

    - #### getPropertyString

          String getPropertyString​(String propertyName)

      Returns the value of a string property. For standard property names, see `MediaDrm.getPropertyString(java.lang.String)`.
      Parameters:
        `propertyName` - The property name.
      Returns:
        The property value.
      Throws:
        `IllegalArgumentException` - If the underlying DRM plugin does not support the property.

    - #### getPropertyByteArray

          byte[] getPropertyByteArray​(String propertyName)

      Returns the value of a byte array property. For standard property names, see `MediaDrm.getPropertyByteArray(java.lang.String)`.
      Parameters:
        `propertyName` - The property name.
      Returns:
        The property value.
      Throws:
        `IllegalArgumentException` - If the underlying DRM plugin does not support the property.

    - #### setPropertyString

          void setPropertyString​(String propertyName,
                                 String value)

      Sets the value of a string property.
      Parameters:
        `propertyName` - The property name.
        `value` - The value.
      Throws:
        `IllegalArgumentException` - If the underlying DRM plugin does not support the property.

    - #### setPropertyByteArray

          void setPropertyByteArray​(String propertyName,
                                    byte[] value)

      Sets the value of a byte array property.
      Parameters:
        `propertyName` - The property name.
        `value` - The value.
      Throws:
        `IllegalArgumentException` - If the underlying DRM plugin does not support the property.

    - #### createMediaCrypto

          ExoMediaCrypto createMediaCrypto​(byte[] sessionId)
                                    throws MediaCryptoException

      Creates an `ExoMediaCrypto` for a given session.
      Parameters:
        `sessionId` - The ID of the session.
      Returns:
        An `ExoMediaCrypto` for the given session.
      Throws:
        `MediaCryptoException` - If an `ExoMediaCrypto` could not be created.

    - #### getExoMediaCryptoType

          Class<? extends ExoMediaCrypto> getExoMediaCryptoType()

      Returns the `ExoMediaCrypto` type created by `createMediaCrypto(byte[])`.