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()
