<?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 <apiname>ContentAccess::CRightsManager</apiname> class
to manage Digital Rights Management (DRM) rights within a particular DRM agent. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<section><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><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><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 &lt;CAgent&gt; agentArray; 
		
// Get the list of agents 
manager-&gt;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&lt;CRightsInfo&gt; myArray; 
CleanupClosePushL(myArray); 

// Get the rights objects from the agent 
rightsManager-&gt;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-&gt;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-&gt;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&lt;CVirtualPath&gt; array;
CleanupClosePushL(array);

// Get the array of content objects associated with the rights 
rightsManager-&gt;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><title>See also</title> <p> <xref href="GUID-920CF819-645B-5705-8017-C1FAD7C6ABAF.dita">Manager
API Tutorials</xref> </p> </section>
</conbody></concept>