|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-A137553F-3B5D-5116-A793-66BF257F42B4" xml:lang="en"><title>Rights |
|
13 Manager API Tutorial</title><shortdesc>Applications can use the <apiname>ContentAccess::CRightsManager</apiname> class |
|
14 to manage Digital Rights Management (DRM) rights within a particular DRM agent. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
15 <section><title>Required background</title> <p>Before you start, you must |
|
16 understand: </p> <ul> |
|
17 <li id="GUID-07B8B672-591F-5188-A6B6-A8369627CCA0"><p> <xref href="GUID-84B6389A-55CC-53EB-8725-65F753FD7217.dita"> Content |
|
18 Access Framework for DRM</xref> </p> </li> |
|
19 <li id="GUID-DB0B1394-6A5F-50DD-B730-9B7D70EDEE6F"><p> <xref href="GUID-29677CD7-DC09-590E-85AC-FF563233A205.dita"> Digital |
|
20 Rights Management</xref> </p> </li> |
|
21 </ul> </section> |
|
22 <section><title>Introduction</title> <p>Rights Manager API gives simple access |
|
23 to the rights within a CAF agent implementing a DRM scheme. The rights are |
|
24 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. |
|
25 This class holds a text description of the rights and some simple properties |
|
26 associated with these rights. </p> <p>Rights Manager API also allows applications |
|
27 to determine which content files are associated with each rights object and |
|
28 vice versa. </p> </section> |
|
29 <section><title>Procedure</title> <ol id="GUID-0DAC3612-40B3-5CA7-A931-D06A94658C40"> |
|
30 <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> |
|
31 <li id="GUID-A0E3D75A-BFC7-5F7D-A58D-00B0C0323642"><p>Perform one or more |
|
32 of the following tasks as per your requirement: </p> <ul> |
|
33 <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> |
|
34 <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> |
|
35 <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> |
|
36 <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> |
|
37 <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> |
|
38 <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> |
|
39 </ul> </li> |
|
40 </ol><p><b id="GUID-A5D2126D-E744-5376-88E4-40AC9BFF92A4">Create a DRM rights |
|
41 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 |
|
42 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 |
|
43 at the rights stored by a particular content access agent. </p><codeblock xml:space="preserve">// create the CManager object |
|
44 CManager manager = CManager::NewL(); |
|
45 |
|
46 // Create RPointerArray to store pointers to the agents |
|
47 RPointerArray <CAgent> agentArray; |
|
48 |
|
49 // Get the list of agents |
|
50 manager->ListAgentsL(agentArray); |
|
51 |
|
52 // Create a CRightsManager for the first agent |
|
53 CRightsManager *rightsManager = manager->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 |
|
54 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 |
|
55 RStreamablePtrArray<CRightsInfo> myArray; |
|
56 CleanupClosePushL(myArray); |
|
57 |
|
58 // Get the rights objects from the agent |
|
59 rightsManager->ListAllRightsL(myArray); |
|
60 |
|
61 // count the number of rights objects |
|
62 TInt numRights = myArray.Count(); |
|
63 |
|
64 // clear the contents of the array |
|
65 myArray.ResetAndDestroy();</codeblock><p><b id="GUID-080F1FCA-ACC0-52F6-8BA7-7CC2DB52F2E0">List |
|
66 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 |
|
67 produces a list of all the rights stored in the given DRM agent that are associated |
|
68 with the file at a given URI. </p><codeblock xml:space="preserve">// Get the rights objects associated with the content |
|
69 rightsManager->ListRightsL(myArray, uri); |
|
70 |
|
71 // Count the number of rights objects associated with the content |
|
72 TInt numRights = myArray.Count(); |
|
73 |
|
74 // clear the contents of the array |
|
75 myArray.ResetAndDestroy();</codeblock><p><b id="GUID-6E6BC94B-7C94-53AD-9A21-73FAE10C2C9B">List |
|
76 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 |
|
77 produces a list of all the rights stored in the given DRM agent that are associated |
|
78 with the content object at a given virtual path.</p><codeblock xml:space="preserve">// Get the rights objects assocated with the content |
|
79 rightsManager->ListRightsL(myArray, virtualPath); |
|
80 |
|
81 // Count the number of rights objects associated with the content |
|
82 TInt numRights = myArray.Count(); |
|
83 |
|
84 // clear the contents of the array |
|
85 myArray->ResetAndDestroy();</codeblock><p><b id="GUID-6B5A514E-4399-5292-9D3D-1E1DBB861338">List |
|
86 the content associated with a rights object</b></p><p>The CRightsManager::ListContentL() |
|
87 function produces a list of all the content that is associated with the given |
|
88 rights object. <codeblock xml:space="preserve">rightsManager->ListAllRightsL(myArray); |
|
89 |
|
90 // get the first CRightsInfo object |
|
91 CRightsInfo* aRightsObject = myArray[0]; |
|
92 |
|
93 RStreamablePtrArray<CVirtualPath> array; |
|
94 CleanupClosePushL(array); |
|
95 |
|
96 // Get the array of content objects associated with the rights |
|
97 rightsManager->ListContentL(array, aRightsObject); |
|
98 |
|
99 // count the number of content objects |
|
100 TInt numContentObjects = array.Count();</codeblock></p><p><b id="GUID-29DC21D6-900C-5EF3-84D6-1FE89FE8FD1D">Retrieve |
|
101 a rights object</b></p><p>The CRightsManager::GetRightsDataL() function allows |
|
102 an application to retrieve a pointer to a rights object. The rights object |
|
103 is derived from MAgentRightsBase. </p><codeblock xml:space="preserve">// Retrieve the full rights object |
|
104 // The application needs to cast it to the agent's derived Rights class before using it. |
|
105 |
|
106 MAgentRightsBase *rightsObject = rightsManager->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 |
|
107 allows an application to delete rights stored by the agent. <codeblock xml:space="preserve">// Delete the rights object |
|
108 TInt result = rightsManager->DeleteRightsObject(aRightsObject);</codeblock> </p><p>It |
|
109 is also possible to delete all the rights associated with a particular content |
|
110 object. </p><codeblock xml:space="preserve">// Delete all the rights objects associated with the given content object |
|
111 TInt result = rightsManager->DeleteAllRights(virtualPath);</codeblock> </section> |
|
112 <section><title>See also</title> <p> <xref href="GUID-920CF819-645B-5705-8017-C1FAD7C6ABAF.dita">Manager |
|
113 API Tutorials</xref> </p> </section> |
|
114 </conbody></concept> |