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.
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 );
}
}
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 );
}
}
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.
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
}
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.
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.
The method CDRMHelper::SupportedDRMMethods2 gives information
about the supported DRM methods and the supported OMA DRM specification version.
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.
Content which does not have Rights or for which the Rights have expired
can be activated by calling the method CDRMHelper::ActivateContentL.
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 );
}
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 );
}
Some methods may leave. Normal Symbian error handling practices should
be used, including e.g. using cleanup stack and TRAP harness.
DRM Helper does not consume memory significantly after creating the object.
There are no possible extensions to this API.