DRM Helper API Specification

1 Overview

DRM Helper API is an interface for handling DRM-specific error situations (such as Rights expiration and missing Rights), registering and unregistering DRM-protected content as automated content, and getting details of DRM-protected content. It also provides some convenience functions for handling OMA DRM v2.0 DCF files.

API category	public
API type	c++
Existed since	Legacy S60 2.6
API libraries	DRMHelper.lib
Location	`/sf/mw/drm/drm_pub/drm_helper_api`
Buildfiles	`/sf/mw/drm/drm_pub/drm_helper_api/group/bld.inf`

1.1 Description

DRM Helper API is intended for applications, which need to deal with DRM protected content. It can be categorized as a library API and its type is a method call interface.

1.2 Use Cases

DRM Helper API can be used for the following use cases:

Handling errors related to invalid rights
Checking status of the rights
Getting rights details
Registering DRM-protected content for automated use
Getting a list of DRM protected contents
Handling DRM-supported MIME-type list
Getting information about supported DRM methods
Controlling rights consumption
Activating content
Handling previews
Handling information about URL

1.3 Class Structure

Summary of API classes and header files
Classes	Files

CDRMHelper /epoc32/include/mw/DRMHelper.h CDRMHelperRightsConstraints /epoc32/include/mw/DRMHelper.h RDRMHelper /epoc32/include/mw/rdrmhelper.h No classes/epoc32/include/mw/DRMHelperServerInternalCRKeys.h, /epoc32/include/platform/mw/loc/sc/drmcommon.loc

The following class diagram shows the main classes of DRM Helper API:

Class diagram of DRM Helper API

2 Using The API

The following explains how the DRM Helper services are accessed through CDRMHelper and CDRMHelperRightsConstraints .

Before using any DRM Helper services, the user must create an instance of the CDRMHelper class by using one of the NewL() or NewLC() methods. It is recommended to use the version that takes CCoeEnv as a parameter. Also if the user already has an open session to the file server, it is recommended to use the version that takes a reference to it as parameter, so that DRM Helper does not open another session to the file server. The user is not supposed to create instances of the CDRMHelperRightsConstraints class; they are only acquired using the CDRMHelper::GetRightsDetailsL() method. The user is responsible for deleting the CDRMHelper and CDRMHelperRightsConstraints instances after the usage.

2.1 Handling errors related to invalid rights

The CDRMHelper::HandleErrorL() or CDRMHelper::HandleErrorOrPreviewL() method can be used to handle DRM-specific errors. CDRMHelper::HandleErrorOrPreviewL() can fetch rights without user interaction if that is allowed and by using it, it is also possible to support embedded preview and preview rights.

The following example illustrates how to use CDRMHelper::HandleErrorL() :

TRAPD( err, FooL() ); // FooL leaves with some errorcode
if ( err != KErrNone )
	{
  if ( iDRMProtected ) // Handle DRM related errors
    {
    CDRMHelper* drmHelper = CDRMHelper::NewLC( *CEikonEnv:Static() );
    TRAPD( err, drmHelper->HandlerErrorL( err, iFileName ) );
    CleanupStack::PopAndDestroy( drmHelper );
    if ( !err )
      {
      // Already handled
      return;
      }
    }
  // Handle non-DRM related errors
  iEikonEnv->HandleError( err );
	}

The following example illustrates how to use CDRMHelper::HandleErrorOrPreviewL() :

TRAPD( err, FooL() ); // FooL leaves with some errorcode
if ( err != KErrNone )
	{
  if ( iDRMProtected ) // Handle DRM related errors
    {
    RFile file;
    HBufC8* embeddedPreview = NULL;
    CDRMHelper* drmHelper = CDRMHelper::NewLC( *CEikonEnv:Static() );
    // this example uses audio
    drmHelper->SetPreviewMediaType( CDRMHelper::EPreviewTypeAudio );
    // Open the file
    file.Open( iFs, iFileName, EFileRead | EFileShareReadersOrWriters );
    TRAP( err,
        drmHelper->HandlerErrorOrPreviewL( err, file, embeddedPreview ) );
    // close the file
    file.Close();
    if ( !err )
      {
      if ( embeddedPreview )
        {
        // play embedded preview
        // after playing preview is completed, call
        // CDRMHelper::EmbeddedPreviewCompletedL
        TBool rightsAcquired =
          iDRMHelper->EmbeddedPreviewCompletedL( iFileName );
        }
      }
    else
      {
      iEikonEnv->HandleError( err );
      }
    CleanupStack::PopAndDestroy( drmHelper );
    }
  else
    {
    // Handle non-DRM related errors
    iEikonEnv->HandleError( err );
    }
	}

2.2 Checking status of the rights

The methods CDRMHelper::CheckRightsAmountL() and CDRMHelper::CheckRightsPercentL() can be used to check the expiry of Rights.

An example of how to use CDRMHelper::CheckRightsAmountL() . CDRMHelper::CheckRightsPercentL() works in similar manner, but instead of using the fixed limit, a percentage of how many rights are still left compared to original rights is used.

void CMyAppDRMHelper::CheckRightsAmountAndDisplayNoteL()
	{
  if( iFilename )
    {
    CDRMHelper* drmHelper = CDRMHelper::NewLC( *CCoeEnv::Static() );
    drmHelper->CheckRightsAmountL( *iFilename );
    CleanupStack::PopAndDestroy( drmHelper );
    }
	}

2.3 Getting rights details

There are two ways of getting Rights details using this API. The CDRMHelper::LaunchDetailsViewEmbeddedL() method opens the DRM Rights Manager UI Details view for a given content. The CDRMHelper::GetRightsDetailsL() and CDRMHelperRightsConstraints methods gets the corresponding information about the rights.

2.4 Registering DRM-protected content for automated use

The CDRMHelper::CanSetAutomated() method is used to check if certain DRM protected content can be set as an automated content. Then, the CDRMHelper::SetAutomated* methods are used to register the DRM-protected content to be used as an automated content. After automated content has been changed to something else, it must be unregistered using the CDRMHelper::RemoveAutomated* methods. The method CDRMHelper::SetAutomatedType must be called before calling the CDRMHelper::SetAutomated* methods to set the type of the automated content.

The following example illustrates how to register DRM protected content for automated use:

TBool canSetAutomated( EFalse );
User::LeaveIfError( iDRMHelper->CanSetAutomated( aFileName, canSetAutomated ) );
if ( canSetAutomated )
	{
  // In this example we are setting a ringing tone
  iDRMHelper->SetAutomatedType( CDRMHelper::EAutomatedTypeRingingTone );
  TInt error( iDRMHelper->SetAutomatedPassive( aFileName ) );
  if ( error != KErrCancel )
    {
    User::LeaveIfError( error );
    // User accepted set as automated
    return ETrue;
  	  }
  return EFalse; // User didn't accept set as automated
	}

2.5 Getting a list of DRM-protected contents

The CDRMHelper::GetContentURIList() method is used to get a list of the content URIs of all the DRM contents in the device.

2.6 Handling DRM supported MIME-type list

The method CDRMHelper::DataTypesCount can be used to get the amount of MIME types supported by the DRM system. Then, the supported MIME types can be queried by CDRMHelper::SupportedDataType one by one. The user of this API can also add new MIME types to the list or remove MIME types from the list by using the methods CDRMHelper::RegisterDataType and CDRMHelper::UnRegisterDataType respectively.

2.7 Getting information about supported DRM methods

The method CDRMHelper::SupportedDRMMethods2 gives information about the supported DRM methods and the supported OMA DRM specification version.

2.8 Controlling rights consumption

The CDRMHelper::Consume2 and CDRMHelper::ConsumeFile2 methods are used to control the Rights of the content are consumed. These methods require the DRM capability. Rights consumption can also be controlled through CAF API with use of intents.

2.9 Activating content

Content which does not have Rights or for which the Rights have expired can be activated by calling the method CDRMHelper::ActivateContentL() .

2.10 Handling previews

The method CDRMHelper::HasPreviewL tells if the given content has an embedded preview or if it is possible to acquire preview Rights for it. Preview Rights can then be acquired by calling the method CDRMHelper::GetPreviewRightsL() . If embedded preview is played, the method CDRMHelper::EmbeddedPreviewCompletedL() should be called after the playback has been stopped to display the appropriate UI notes.

The CDRMHelper::HandleErrorOrPreviewL() method provides an option to play embedded preview or acquire preview rights if the content does not have valid rights and it has either embedded preview or preview URL. If content does not have either embedded preview, preview URL or silent rights, CDRMHelper::HandleErrorOrPreviewL() works like CDRMHelper::HandleErrorL() . Prior to calling CDRMHelper::HandleErrorOrPreviewL() , CDRMHelper::SetPreviewMediaType must be called.

The following example illustrates how to check if content has an embedded preview and handle it:

TDRMHelperPreviewType previewType =
  iDRMHelper->HasPreviewL( fileName, iPreviewUri );
if ( previewType == CDRMHelper::EEmbeddedPreview );
	{
  // content has an embedded preview available, enable 'play preview' menu item.
	}
CMyApp::HandleCommandL()
	{
  // user has selected the 'play preview' menu item, play preview
  // after playing preview is completed, call
  // CDRMHelper::EmbeddedPreviewCompletedL
  TBool rightsAcquired = iDRMHelper->EmbeddedPreviewCompletedL( filename );
	}

2.11 Handling information URL

The method CDRMHelper::HasInfoUrlL() can be used to check if the given content has an information URL. The CDRMHelper::OpenInfoUrlL() method can be then used to open Browser with the information URL.

The following example illustrates how to handle information URLs:

if ( iDRMHelper->HasInfoUrlL( fileName, infoUrl ) )
	{
  // Content has info URL, enable 'more info online' menu item
	}
CMyApp::HandleCommandL()
	{
  // user has selected the 'more info online' menu item
  iDRMHelper->OpenInfoUrlL( fileName );
	}

2.12 Error handling

Some methods may leave. Normal Symbian error handling practices must be used, for example, using cleanup stack and TRAP harness.

2.13 Memory and Performance Considerations

DRM Helper does not consume memory significantly after creating the object.

2.14 Extensions to the API

There are no possible extensions to this API.