<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-A137553F-3B5D-5116-A793-66BF257F42B4" xml:lang="en"><title>Rights

Manager API Tutorial</title><shortdesc>Applications can use the <codeph>ContentAccess::CRightsManager</codeph> class

to manage Digital Rights Management (DRM) rights within a particular DRM agent. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-B080A3A2-FDD5-4F98-B3FE-D68D5A49B237"><title>Required background</title> <p>Before you start, you must

understand: </p> <ul>

<li id="GUID-07B8B672-591F-5188-A6B6-A8369627CCA0"><p> <xref href="GUID-84B6389A-55CC-53EB-8725-65F753FD7217.dita"> Content

Access Framework for DRM</xref> </p> </li>

<li id="GUID-DB0B1394-6A5F-50DD-B730-9B7D70EDEE6F"><p> <xref href="GUID-29677CD7-DC09-590E-85AC-FF563233A205.dita"> Digital

Rights Management</xref> </p> </li>

</ul> </section>

<section id="GUID-A89F8ADE-7820-4867-8BE8-0165E3A4BB35"><title>Introduction</title> <p>Rights Manager API gives simple access

to the rights within a CAF agent implementing a DRM scheme. The rights are

represented in a generic form using the <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-1C5F342A-2425-33C6-9769-90B3EC98A213"><apiname>ContentAccess::CRightsInfo</apiname></xref> class.

This class holds a text description of the rights and some simple properties

associated with these rights. </p> <p>Rights Manager API also allows applications

to determine which content files are associated with each rights object and

vice versa. </p> </section>

<section id="GUID-B18DBC90-1E91-41E8-8153-5BEEEEAA5559"><title>Procedure</title> <ol id="GUID-0DAC3612-40B3-5CA7-A931-D06A94658C40">

<li id="GUID-AB4439A9-3CF6-51F8-AB1B-381E7A8CD399"><p> <xref href="GUID-A137553F-3B5D-5116-A793-66BF257F42B4.dita#GUID-A137553F-3B5D-5116-A793-66BF257F42B4/GUID-A5D2126D-E744-5376-88E4-40AC9BFF92A4">Create a DRM rights management object</xref>. </p> </li>

<li id="GUID-A0E3D75A-BFC7-5F7D-A58D-00B0C0323642"><p>Perform one or more

of the following tasks as per your requirement: </p> <ul>

<li id="GUID-340B8678-49FF-5B40-B9B2-BA5FD6E60CA2"><p> <xref href="GUID-A137553F-3B5D-5116-A793-66BF257F42B4.dita#GUID-A137553F-3B5D-5116-A793-66BF257F42B4/GUID-1E57BE18-5EFF-587C-A263-2606BE557DC4">List all rights objects</xref>. </p> </li>

<li id="GUID-23853DD9-B8F1-5EF3-A462-C08BF134C563"><p> <xref href="GUID-A137553F-3B5D-5116-A793-66BF257F42B4.dita#GUID-A137553F-3B5D-5116-A793-66BF257F42B4/GUID-080F1FCA-ACC0-52F6-8BA7-7CC2DB52F2E0">List the rights associated with a content file</xref>. </p> </li>

<li id="GUID-4E40636C-B3D7-5D73-A97C-09B306606CD4"><p> <xref href="GUID-A137553F-3B5D-5116-A793-66BF257F42B4.dita#GUID-A137553F-3B5D-5116-A793-66BF257F42B4/GUID-6E6BC94B-7C94-53AD-9A21-73FAE10C2C9B">List the rights associated with a content object</xref>. </p> </li>

<li id="GUID-1646306D-47A8-5AAB-A4A2-11DC2FA19403"><p> <xref href="GUID-A137553F-3B5D-5116-A793-66BF257F42B4.dita#GUID-A137553F-3B5D-5116-A793-66BF257F42B4/GUID-6B5A514E-4399-5292-9D3D-1E1DBB861338">List the content associated with a rights object</xref>. </p> </li>

<li id="GUID-0AB8C520-52A7-5CDB-9AD3-E1B67558D659"><p> <xref href="GUID-A137553F-3B5D-5116-A793-66BF257F42B4.dita#GUID-A137553F-3B5D-5116-A793-66BF257F42B4/GUID-29DC21D6-900C-5EF3-84D6-1FE89FE8FD1D">Retrieve a rights object</xref>. </p> </li>

<li id="GUID-7572CDFF-15B8-505F-B762-1A67B0A1457C"><p> <xref href="GUID-A137553F-3B5D-5116-A793-66BF257F42B4.dita#GUID-A137553F-3B5D-5116-A793-66BF257F42B4/GUID-6B934FC5-76EC-599E-914C-7AB1D553F171">Delete a rights object</xref>. </p> </li>

</ul> </li>

</ol><p><b id="GUID-A5D2126D-E744-5376-88E4-40AC9BFF92A4">Create a DRM rights

management object</b></p><p>The <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-2CBEF3AA-7101-3247-BAED-79B624CEBBD1"><apiname>ContentAccess::CRightsManager</apiname></xref>object

is created by the <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-671191B1-B249-3DD3-A5E8-6F1A41A371C8"><apiname>ContentAccess::CManager</apiname></xref> object to look

at the rights stored by a particular content access agent. </p><codeblock xml:space="preserve">// create the CManager object

CManager manager = CManager::NewL(); 

// Create RPointerArray to store pointers to the agents 

RPointerArray <CAgent> agentArray; 

// Get the list of agents 

manager->ListAgentsL(agentArray); 

// Create a CRightsManager for the first agent	

CRightsManager *rightsManager = manager-&gt;CreateRightsManagerL(agentArray[0]);</codeblock><p><b id="GUID-1E57BE18-5EFF-587C-A263-2606BE557DC4">List all rights objects</b></p><p>The <xref href="GUID-C4B8AE31-6ABD-3FEA-88DD-3B4EE13ACF49.dita#GUID-C4B8AE31-6ABD-3FEA-88DD-3B4EE13ACF49/GUID-35127771-EAC1-3DB7-9B53-53898C75ECF0"><apiname>CRightsManager::ListAllRightsL()</apiname></xref> function

produces a list of all the rights stored in the given DRM agent. </p><codeblock xml:space="preserve">// Create the array to store rights objects 

RStreamablePtrArray<CRightsInfo> myArray; 

CleanupClosePushL(myArray); 

// Get the rights objects from the agent 

rightsManager->ListAllRightsL(myArray); 

// count the number of rights objects 

TInt numRights = myArray.Count(); 

// clear the contents of the array

myArray.ResetAndDestroy();</codeblock><p><b id="GUID-080F1FCA-ACC0-52F6-8BA7-7CC2DB52F2E0">List

the rights associated with a content file</b></p><p>The<xref href="GUID-C4B8AE31-6ABD-3FEA-88DD-3B4EE13ACF49.dita#GUID-C4B8AE31-6ABD-3FEA-88DD-3B4EE13ACF49/GUID-A2EFFC6C-13B6-33BD-82B1-57CBBCA19F8C"><apiname> CRightsManager::ListRightsL()</apiname></xref> function

produces a list of all the rights stored in the given DRM agent that are associated

with the file at a given URI. </p><codeblock xml:space="preserve">// Get the rights objects associated with the content 

rightsManager->ListRightsL(myArray, uri); 

// Count the number of rights objects associated with the content 

TInt numRights = myArray.Count(); 

// clear the contents of the array 

myArray.ResetAndDestroy();</codeblock><p><b id="GUID-6E6BC94B-7C94-53AD-9A21-73FAE10C2C9B">List

the rights associated with a content object</b></p><p>The <xref href="GUID-C4B8AE31-6ABD-3FEA-88DD-3B4EE13ACF49.dita#GUID-C4B8AE31-6ABD-3FEA-88DD-3B4EE13ACF49/GUID-A2EFFC6C-13B6-33BD-82B1-57CBBCA19F8C"><apiname>CRightsManager::ListRightsL()</apiname></xref> function

produces a list of all the rights stored in the given DRM agent that are associated

with the content object at a given virtual path.</p><codeblock xml:space="preserve">// Get the rights objects assocated with the content 

rightsManager->ListRightsL(myArray, virtualPath); 

// Count the number of rights objects associated with the content 

TInt numRights = myArray.Count(); 

// clear the contents of the array 

myArray-&gt;ResetAndDestroy();</codeblock><p><b id="GUID-6B5A514E-4399-5292-9D3D-1E1DBB861338">List

the content associated with a rights object</b></p><p>The CRightsManager::ListContentL()

function produces a list of all the content that is associated with the given

rights object. <codeblock xml:space="preserve">rightsManager-&gt;ListAllRightsL(myArray);

// get the first CRightsInfo object 

CRightsInfo* aRightsObject = myArray[0]; 

RStreamablePtrArray<CVirtualPath> array;

CleanupClosePushL(array);

// Get the array of content objects associated with the rights 

rightsManager->ListContentL(array, aRightsObject); 

// count the number of content objects

TInt numContentObjects = array.Count();</codeblock></p><p><b id="GUID-29DC21D6-900C-5EF3-84D6-1FE89FE8FD1D">Retrieve

a rights object</b></p><p>The CRightsManager::GetRightsDataL() function allows

an application to retrieve a pointer to a rights object. The rights object

is derived from MAgentRightsBase.  </p><codeblock xml:space="preserve">// Retrieve the full rights object

// The application needs to cast it to the agent's derived Rights class before using it. 

MAgentRightsBase *rightsObject = rightsManager-&gt;GetRightsDataL(aRightsObject);</codeblock><p><b id="GUID-6B934FC5-76EC-599E-914C-7AB1D553F171">Delete a rights object</b></p><p>The <xref href="GUID-C4B8AE31-6ABD-3FEA-88DD-3B4EE13ACF49.dita#GUID-C4B8AE31-6ABD-3FEA-88DD-3B4EE13ACF49/GUID-1F0BE582-5C12-3880-9951-56B7B209FEC1"><apiname>CRightsManager::DeleteRightsObject()</apiname></xref> function

allows an application to delete rights stored by the agent. <codeblock xml:space="preserve">// Delete the rights object 

TInt result = rightsManager-&gt;DeleteRightsObject(aRightsObject);</codeblock> </p><p>It

is also possible to delete all the rights associated with a particular content

object.  </p><codeblock xml:space="preserve">// Delete all the rights objects associated with the given content object 

TInt result = rightsManager-&gt;DeleteAllRights(virtualPath);</codeblock> </section>

<section id="GUID-64D1E9E3-775F-4B50-8469-78F6600E4852"><title>See also</title> <p> <xref href="GUID-920CF819-645B-5705-8017-C1FAD7C6ABAF.dita">Manager

API Tutorials</xref> </p> </section>