Using the DRMHandler class

The provided prm-encrypted-playback example code demonstrates how to set up PRM-encrypted playback using PRM Indirect mode with the assistance of various classes in the pak directory of the example code.

The pak directory (com.nagra.example.prmencrypted.pak package) contains a set of classes that simplify access to the objects in the PAK libraries, in particular, the PakCore class.

This package provides a DRMHandler singleton class that handles all access to the PAK resources. It is supported by operation delegates (for different access modes), listeners, and other helper classes, thus eliminating the need to access the PakCore directly.

Setting up the PAK operations using DRMHandler

At the heart of the set-up is the call to DRMHandler.creatInstance(); there are a few steps before and after this call.

1. Implement a DRMHandlerListener class
2. Implement a DRMHandlerResponse class
3. Instantiate a DRMHandlerRequest object
4. Instantiate one of the DRMHandlerOperationDelegate objects, depending on the operation mode
5. Create the DRMHandler instance
6. Initialise the DRMHandler

Implementing a DRMHandlerListener class

The DRMHandlerListener is an interface with a single method to implement - licenseAcquisitionNeeded() for handling a license request.

  DRMHandlerListener drmHandlerListener = new DRMHandlerListener() {
      @Override
      public void licenseAcquisitionNeeded(DRMHandlerRequest request) {
          request.setServerUrl("https://path/to/license/server");
          DRMHandler.getInstance().acquireLicense(request, mDrmHandlerResponse);
      }
  };

Whenever PAK requires a license, it calls licenseAcquisitionNeeded(), which, in the case of Indirect mode, builds an acquireLicense SOAP request and sends it to the license server (asynchronously). 

If the response from the license server is successful, the response payload will be used to extract the license keys and push them into the PAK's entitlement objects.

Implementing a DRMHandlerResponse class

The DRMHandlerResponse interface allows the application to act upon various response events coming from the PAK.

DRMHandlerResponse drmHandlerResponse = new DRMHandlerResponse() {
    @Override
    public void setPrivateData(String xPrivateData) {
      // sets private data
    }
    @Override
    public void licenseAdded(DRMLicense xLicense) {
      // License added
    }
    @Override
    public void licenseRemoved(DRMLicense xLicense) {
      // License removed
    }
    @Override
    public void finished() {
      // Finished request without error
    }
    @Override
    public void finishedWithError(DRMHandlerError xError) {
      // Finished with specified error
    }
  };

Instantiating a DRMHandlerRequest object

DRMHandlerRequest is a data class containing all the request parameters. It is initialised with default values and later on configured with its parameters. This object is subsequently passed on in DRMHandlerListener.licenseAcquisitionNeeded(request).

DRMHandlerRequest request = new DRMHandlerRequest();
request.setPersistLicense(false);                       // Set to 'true' if license is used for offline (D2G) playback
request.setServerUrl("https://path/to/license/server");
request.setClearPrivateData("clear_private_data");      // Used in Direct mode to initialize or request license

Instantiating a DRMHandlerOperationDelegate object

Three classes implement a delegate for one of the three modes available.

• DRMHandlerDirectOperationDelegate
• DRMHandlerIndirectOperationDelegate
• DRMHandlerNonSilentDirectOperationDelegate

Only one of these needs to be instantiated. The different delegate implementations facilitate the various operation modes. In the example below, the delegate for Indirect mode is created.

DRMHandlerOperationDelegate delegate = new DRMHandlerIndirectOperationDelegate();

Creating the DRMHandler instance

When everything is ready, you can create the handler instance. The delegate and the handler listener are used to create the DRMHandler singleton instance.

DRMHandler drmHandler = DRMHandler.createInstance(drmHandlerListener, delegate, getApplicationContext());

This initialises the PAK (instantiates the pakCore, sets its OpVault, debug levels and other configuration parameters, and registers listener and callback classes).

Initialise the DRMHandler

You now need to initialise the instance.

drmHandler.initialize(request, drmHandlerResponse);

In the case of an Indirect delegate, this will fetch from the PAK the device ID and the PRM initialisation payload, build an Initialize SOAP request, and send it to the license server (asynchronously). 

If the response from the licence server is successful, the response's payload will be used to pass back to the PAK. The response from the server also triggers one of the DRMHandlerResponse callbacks - setPrivateData() with finished(), or finishedWithError().

For other modes, the different delegates behave slightly differently but based on the same principles.

Next step:  Playback of content