Purpose

The DRM Utility 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 displaying details of DRM-protected content. It supports both OMA DRM and WMDRM.

API Description

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

Use cases

The DRM Utility API can be used for following use cases:

  • Checking if content is DRM-protected.

  • Handling errors related to invalid rights and acquiring new rights when possible.

  • Checking the status of the rights.

  • Displaying details of the rights.

  • Handling automated use of DRM-protected content.

  • Handling DRM-specific URLs defined in the content.

  • Checking rights status with content ID.

API class structure

The main classes of DRM Utility API are displayed in Figure 1 below. The clients of this API use CDrmAutomatedUsage, CDrmUiHandling and/or CDrmRightsInfo classes. They may also implement some of the observer classes to control the behavior of DRM Utility.

Class diagram of DRM Utility API


Class diagram of DRM Utility API

Related APIs
  • CDrmAutomatedUsage
  • CDrmRightsInfo
  • CDrmUiHandling

Using the DRM Utility API

The following chapters explain how the DRM Utility services are accessed through CDrmRightsInfo, CDrmUiHandling and CDrmAutomatedUsage classes and how to implement observers.

Checking if content is DRM-protected

DRM::CDrmUtility class contains method IsProtectedL which can be used to check if a file is DRM-protected. The following example shows how it can be used. Reference to DRM::CDrmUtility class can also be acquired by using DRM::CDrmUIHandling::GetUtility or DRM::CDrmAutomatedUsage::GetUtility methods.

// open file 
RFile file; 
User::LeaveIfError( 
    file.Open( iFs, aFileName, EFileRead | EFileShareReadersOrWriters ) ); 
CleanupClosePushL( file );  

// Call NewLC() to create an instance of CDrmUtility.  
DRM::CDrmUtility* drmUtility = DRM::CDrmUtility::NewLC();

if ( drmUtility->IsProtectedL( file ) )     
    {     
    // file is protected
    } 
else     
    {     
    // file is not protected (it may still be a null-encrypted drm file)
    }      

// delete drmUtility 
CleanupStack::PopAndDestroy( drmUtility );
 
// Close file 
CleanupStack::PopAndDestroy();

Related APIs
  • DRM::CDrmAutomatedUsage::GetUtility
  • DRM::CDrmUIHandling::GetUtility
  • DRM::CDrmUtility
  • IsProtectedL

Handling errors related to invalid rights

If opening of DRM-protected file fails because of invalid rights, the situation can be resolved by using the DRM Utility API.

Here is an example how to resolve the situation by using the HandleErrorAsyncL method.

// open file 
User::LeaveIfError( 
    iFile.Open( iFs, aFileName, EFileRead | EFileShareReadersOrWriters ) ); 

// Call NewL() to create an instance of CDrmUiHandling.  
iDrmUiHandler = DRM::CDrmUiHandling::NewL( CCoeEnv::Static() );  

// pass error that occured while trying to open the file to HandleErrorL  
// in this example, we assume that content was tried to play 
TInt operationId = iDrmUiHandler->GetErrorHandler().HandleErrorAsyncL( 
    iFile, ContentAccess::EPlay, error, this ); 

// implement callbacks 
DRM::TEmbeddedPreviewAction CMyClass::EmbeddedPreviewAvailable( 
    TInt aOperationId, 
    const TDesC& aUniqueId, 
    TInt aRightsStatus,
    TInt aReason )     
    {   
    // in this example we let DRM Utility to ask user if he/she wants to play 
    // embedded preview     
    return DRM::EUEmbeddedPreviewActionDefault;     
    }    
 
DRM::TPreviewRightsAction CMyClass::PreviewRightsUrlAvailable( 
    TInt aOperationId,
    const TDesC aPreviewRightsUrl,
    TInt aRightsStatus, 
    TInt aReason )     
    {     
    // in this example we let DRM Utility to handle the preview rights URL     
    return DRM::EUPreviewRightsActionDefault;     
    }
     
DRM::TSilentRightsAction CMyClass::SilentRightsUrlAvailable( 
    TInt aOperationId,
    const TDesC& aSilentRightsUrl,
    TInt aRightsStatus,
    TInt aReason )     
    {     
    // in this example we let DRM Utility to handle the silent rights URL     
    return DRM::EUSilentRightsActionDefault;     
    }  

DRM::TRightsAction CMyClass::RightsUrlAvailable(
    TInt aOperationId,
    const TDesC& aRightsUrl, 
    TInt aRightsStatus, 
    TInt aReason )
    {     
    // in this example we let DRM Utility to handle the rights URL     
    return DRM::EURightsActionDefault;     
    }  

void CMyClass::PreviewRightsAvailable( TInt aOperationId, TInt aError )     
    {     
    // preview rights were retrieved, content can be played now     
    }      

void CMyClass::SilentRightsAvailable( TInt aOperationId, TInt aError )
    {     
    // silent rights were retrieved, content can be played now.    
    }           

void CMyClass::RightsAvailable( TInt aOperationId, TInt aError )
    {     
    // rights were retrieved, content can be played now.    
    }           

void CMyClass::PlayEmbeddedPreviewSelected( 
    TInt aOperationId, 
    const TDesC& aUniqueId )     
    {     
    // play embedded preview part     
    }  

void CMyClass::OperationCompleted( TInt aOperationId, TInt aOperationStatus )
    {     
    if ( aOperationStatus )         
        {         
        // error happened       
        }              

    // close file
    iFile.Close();

    delete iDrmUiHandler;     
    iDrmUiHandler = NULL;      
    }

Related APIs
  • HandleErrorAsyncL

Checking status of the rights

DRM::CDrmUiHandling::CheckRighstAmountL and DRM::CDrmUiHandling::CheckRighstAmountAsyncL can be used to check the status of the rights. The following example elaborates how to use CheckRightsAmountAsyncL.

// open file 
User::LeaveIfError( 
    iFile.Open( iFs, aFileName, EFileRead | EFileShareReadersOrWriters ) ); 

// Call NewL() to create an instance of CDrmUiHandling.  
iDrmUiHandler = DRM::CDrmUiHandling::NewL( CCoeEnv::Static() );  

// check rights, in this example we are going to play the content   
TInt operationId = iDrmUiHandler->CheckRightsAmountAsyncL( 
    file, ContentAccess::EPlay, this ); 

// implement callbacks 
DRM::TCheckRightsAction CMyClass::RightsLeft(      
    TInt aOperationId,
    TBool aUnconstrained,      
    TTimeIntervalSeconds aTime,      
    TInt aCounts,      
    TTimeIntervalSeconds aAccumulated )     
    { 
    // in this example we let DRM Utility to handle this     
    return DRM::EUHCheckRightsActionDefault;
    }     

DRM::TCheckRightsAction CMyClass::RightsNotValid(      
    TInt aOperationId, 
    DRM::TCheckRightsStatus aRightsStatus, 
    TInt aReason )     
    {     
    // in this example we let DRM Utility to handle this     
    return DRM::EUHCheckRightsActionDefault;     
    }  

void CMyClass::OperationCompleted( TInt aOperationId, TInt aOperationStatus )
    {     
    if ( aOperationStatus )         
        {         
        // error happened       
        }              

    // close file
    iFile.Close();

    delete iDrmUiHandler;     
    iDrmUiHandler = NULL;      
    }

Related APIs
  • CheckRightsAmountAsyncL
  • DRM::CDrmUiHandling::CheckRighstAmountAsyncL
  • DRM::CDrmUiHandling::CheckRighstAmountL

Displaying details of the rights

DRM::CDrmUiHandling::ShowDetailsViewL and DRM::CDrmUiHandling::ShowDetailsViewAsyncL methods can be used to display rights details in an embedded details view. The following example shows how ShowDetailsViewAsyncL can be used.

// open file 
User::LeaveIfError( 
    iFile.Open( iFs, aFileName, EFileRead | EFileShareReadersOrWriters ) ); 

// Call NewL() to create an instance of CDrmUiHandling.  
iDrmUiHandler = DRM::CDrmUiHandling::NewL( CCoeEnv::Static() );  

// show details view   
iDrmUiHandler->ShowDetailsViewAsyncL( iFile, this ); 

// implement async callback 
void CMyClass::OperationCompleted( TInt aOperationId, TInt aOperationStatus )     
    {
    if ( aOperationStatus )         
        {         
        // error happened         
        }   
          
    // Close file 
    iFile.Close();  

    delete iDrmUiHandler;     
    iDrmUiHandler = NULL;      
    }

Related APIs
  • DRM::CDrmUiHandling::ShowDetailsViewAsyncL
  • DRM::CDrmUiHandling::ShowDetailsViewL
  • ShowDetailsViewAsyncL

Handling automated use of DRM-protected content

The DRM::CDrmAutomatedUsage class can be used to handle the automated use of DRM-protected content. The following example shows how it can be used to register content for automated use and how to monitor the expiration of automated content.

// open file 
User::LeaveIfError( 
    iFile.Open( iFs, fileName, EFileRead | EFileShareReadersOrWriters ) ); 

// Call NewL() to create an instance of CDrmAutomatedUsage.  
iDrmAutomatedUsage = DRM::CDrmAutomatedUsage::NewL( CCoeEnv::Static() );  

// check if content can be set as automated, 
// in this example we are setting a wallpaper 
if ( iDrmAutomatedUsage->CanSetAutomatedL( 
    iFile, ContentAccess::EView, DRM::EAutomatedTypeWallpaper ) )     
    {     
    // automated usage allowed      

    // register content
    iDrmAutomatedUsage->SetAutomatedAsyncL( 
        iFile, ContentAccess::EView, DRM::EAutomatedTypeWallpaper, this );     
    } 
else     
    {     
    // automated usage not allowed   

    // Close file
    iFile.Close();
    }  

// implement async callback
void CMyClass::OperationCompleted( TInt aOperationId, TInt aOperationStatus )     
    {     
    if ( !aOperationStatus )         
        {         
        // registering successfull, start to listen events         
        iDrmAutomatedUsage->RegisterEventObserverL( this );                 
        }     
    else         
        {         
        // error happened   
        }               
    }  

// Implement automated usage callback 
DRM::TAutomatedUsageAction CMyClass::AutomatedUsageEvent(      
    DRM::TAutomatedUsageEvent aAutomatedUsageEvent,     
    const TDesC& aUniqueId,     
    const DRM::TDrmAutomatedType aType,    
    const DRM::TDrmAutomatedServiceType aServiceType,     
    ContentAccess::TIntent aIntent )     
    {     
    switch ( aAutomatedUsageEvent )
        {
        case DRM::EAUAutomatedContentExpired:
            // some automated content expired                  
            // check unique ID if we are interested about this content         
            if ( !aUniqueId.Compare( myUniqueId ) )             
                {             
                // revert back to default content

                // and let utility to handle the rest             
                return DRM::EAUActionDefault;            
                }           
            break;

        case DRM::EAUAutomatedContentIdleAfterExpired:
            // check unique ID if we are interested about this content         
            if ( !aUniqueId.Compare( myUniqueId ) )             
                {             
                // unregister the content
                iDrmAutomatedUsage->RemoveAutomatedL( 
                    myUniqueId, aIntent, aType );

                // unregister the observer (if this was the only content the
                // observer was interested in)
                iDrmAutomatedUsage->UnregisterEventObserver( this );

                // Close file
                iFile.Close();

                // and let utility to handle the rest             
                return DRM::EAUActionDefault;            
                }           
            break;

        default:
            break;
        }

    return DRM::EAUActionIgnore;     
    }

Related APIs
  • DRM::CDrmAutomatedUsage

Handling DRM-specific URLs defined in the content

By using DRM::CDrmUiHandling::AvailableUrlsL or DRM::CDrmUiHandling::AvailableUrlsAsyncL method the user of this API can check what kind of DRM-specific URLs the content has. In addition, with method DRM::CDrmUiHandling::HandleUrlL or DRM::CDrmUiHandling::HandleUrlL it can handle those URLs. The following example shows how to use these methods to handle Info URL.

// open file  
RFile file;
User::LeaveIfError( 
    file.Open( iFs, fileName, EFileRead | EFileShareReadersOrWriters ) );  
CleanupClosePushL( file );

// Call NewLC() to create an instance of CDrmUiHandling.   
drmUiHandling = DRM::CDrmUiHandling::NewLC( CCoeEnv::Static() );  

// check that content has the info URL 
if ( drmUiHandling->AvailableUrlsL( file ) & DRM::EInfoUrl )          
    {          
    // Handle the Info URL  
    drmUiHandling->HandleUrlL( file, DRM::EInfoUrl );     
    }  

// delete drmUiHandling and close the file
CleanupStack::PopAndDestroy( 2 );

Related APIs
  • DRM::CDrmUiHandling::AvailableUrlsAsyncL
  • DRM::CDrmUiHandling::AvailableUrlsL
  • DRM::CDrmUiHandling::HandleUrlL

Checking rights status with content ID

By using the DRM::CDrmRightsInfo::CheckRightsL() or DRM::CDrmRightsInfo::CheckRightsAsyncL() method, this API can check the status of the rights based on content ID (i.e. not needing to open the content file if the content ID has been got some other way). The following example illustrates the use of DRM::CDrmRightsInfo::CheckRightsL().

DRM::TDrmRightsInfo rightsDetails;  

// Call NewLC() to create an instance of CDrmRightsInfo.    
DRM::CDrmRightsInfo* drmRightsInfo = DRM::CDrmRightsInfo::NewLC();  

// check rights with content ID, in this example the play rights are checked 
drmRightsInfo->CheckRightsL( contentId, ContentAccess::EPlay, rightsDetails );  

switch ( rightsDetails )
    {
    case DRM::EURightsInfoValid:
        // Rights are valid
        break;
    case DRM::EURightsInfoExpired: 
        // Rights have been expired
        break;
    case DRM::EURightsInfoMissing:
        // No rights objects at all for this content
        break;
    case DRM::EURightsInfoFuture:
        // Rights will be valid in future
        break;
    default:
        // should never come here
        break;
    }

// delete drmRightsInfo
CleanupStack::PopAndDestroy( drmRightsInfo );  

Related APIs
  • DRM::CDrmRightsInfo::CheckRightsAsyncL()
  • DRM::CDrmRightsInfo::CheckRightsL()

Error handling

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

Memory overhead

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

Extensions to the API

There are no possible extensions to this API.

Related APIs
  • CDrmAutomatedUsage
  • CDrmRightsInfo
  • CDrmUiHandling

Glossary

Abbreviations

Definitions

References