DRM Helper API: Using DRM Helper 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. Using a version that takes CCoeEnv as a parameter is recommended whenever possible. 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 both CDRMHelper and CDRMHelperRightsConstraints instances after usage.

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.

An example of 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 );
	}

An example of 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 );
    }
	}

Checking status of the rights

The methods CDRMHelper::CheckRightsAmountL() and CDRMHelper::CheckRightsPercentL() can be used to check if Rights are about to expire in the near future.

An example of how to use CDRMHelper::CheckRightsAmountL(). CDRMHelper::CheckRightsPercentL() works in similar manner, but instead of using the fixed limit, a percentage how much there are rights 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 );
    }
	}

Getting rights details

There are two ways of getting Rights details using this API. By calling CDRMHelper::LaunchDetailsViewEmbeddedL(), the user of this API can open the DRM Rights Manager UI Details view for a given content. By calling the CDRMHelper::GetRightsDetailsL() and CDRMHelperRightsConstraints methods, the user of this API can get the corresponding information about the rights.

Registering DRM-protected content for automated use

Using the method CDRMHelper::CanSetAutomated(), the user of this API can first check if certain DRM protected content can be set as an automated content. Then, using the CDRMHelper::SetAutomated* methods, the user of this API can 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 should be called before calling the CDRMHelper::SetAutomated* methods to set the type of the automated content.

Here is an example 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
	}

Getting a list of DRM-protected contents

By using the method CDRMHelper::GetContentURIList(), the user of this API can get a list of the content URIs of all the DRM contents in the device.

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.

Getting information about supported DRM methods

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

Controlling rights consumption

With the methods CDRMHelper::Consume2 and CDRMHelper::ConsumeFile2, the user of this API can control how 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.

Activating content

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

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 method CDRMHelper::HandleErrorOrPreviewL asks the user if he/she wants 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 should be called.

Here is an example 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 );
	}

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.

Here is an example 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 );
	}

Error handling

Some methods may leave. Normal Symbian error handling practices should be used, including e.g. using cleanup stack and TRAP harness.

Memory overhead

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

Extensions to the API

There are no possible extensions to this API.


Copyright © Nokia Corporation 2001-2008
Back to top