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::GetUtilityDRM::CDrmUIHandling::GetUtilityDRM::CDrmUtilityIsProtectedL
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
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
CheckRightsAmountAsyncLDRM::CDrmUiHandling::CheckRighstAmountAsyncLDRM::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::ShowDetailsViewAsyncLDRM::CDrmUiHandling::ShowDetailsViewLShowDetailsViewAsyncL
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
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::AvailableUrlsAsyncLDRM::CDrmUiHandling::AvailableUrlsLDRM::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
CDrmAutomatedUsageCDrmRightsInfoCDrmUiHandling