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 );
}
}
Related APIs
CDRMHelper::HandleErrorL()
CDRMHelper::HandleErrorOrPreviewL()
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 );
}
}
Related APIs
CDRMHelper::CheckRightsAmountL()
CDRMHelper::CheckRightsPercentL()
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.
Related APIs
CDRMHelper::GetRightsDetailsL()
CDRMHelper::LaunchDetailsViewEmbeddedL()
CDRMHelperRightsConstraints
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
}
Related APIs
CDRMHelper::CanSetAutomated()
CDRMHelper::RemoveAutomated*
CDRMHelper::SetAutomated*
CDRMHelper::SetAutomatedType
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.
Related APIs
CDRMHelper::GetContentURIList()
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.
Related APIs
CDRMHelper::DataTypesCount
CDRMHelper::RegisterDataType
CDRMHelper::SupportedDataType
CDRMHelper::UnRegisterDataType
Getting information about supported DRM methods
The method
CDRMHelper::SupportedDRMMethods2
gives information
about the supported DRM methods and the supported OMA DRM specification version.
Related APIs
CDRMHelper::SupportedDRMMethods2
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.
Related APIs
CDRMHelper::Consume2
CDRMHelper::ConsumeFile2
Activating content
Content which does not have Rights or for which the Rights have expired
can be activated by calling the method
CDRMHelper::ActivateContentL
.
Related APIs
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 );
}
Related APIs
CDRMHelper::EmbeddedPreviewCompletedL
CDRMHelper::GetPreviewRightsL
CDRMHelper::HandleErrorL
CDRMHelper::HandleErrorOrPreviewL
CDRMHelper::HasPreviewL
CDRMHelper::SetPreviewMediaType
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 );
}
Related APIs
CDRMHelper::HasInfoUrlL
CDRMHelper::OpenInfoUrlL
Error handling
Some methods may leave. Normal Symbian error handling practices should
be used, including e.g. using cleanup stack and
TRAP
harness.
Related APIs
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.
Related APIs
CCoeEnv
CDRMHelper
CDRMHelper::GetRightsDetailsL()
CDRMHelperRightsConstraints
NewL()
NewLC()