|
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-09A760FD-4C2A-5F79-91F2-DCC25A63699C" xml:lang="en"><title>Handling |
|
13 DRM Content</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>Content Access Framework (CAF) provides services that enable agents to |
|
15 publish content in a generic manner that is easy for applications to use. |
|
16 Applications use the Consumer API to render a content and multimedia plug-ins. </p> |
|
17 <p> <b>Note:</b> Rendering is a process of reading data from a file, transforming |
|
18 it, then playing or displaying it on the device. </p> |
|
19 <p><b>Access to content within archive files </b> </p> |
|
20 <p>An archive file contains content objects and other containers within the |
|
21 file. Each container within the file may contain more content objects or further |
|
22 containers. Common examples of archive files are zip and tar files. </p> |
|
23 <p>CAF allows applications to open archive files and read content from inside |
|
24 them. The content objects and containers inside the file can be traversed |
|
25 using the <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-FC40011B-32D3-328B-BB59-35BEF46A215A"><apiname>ContentAccess::CContent</apiname></xref> class. The class allows |
|
26 applications to use the content within these container files without needing |
|
27 to understand any specifics of the compression or storage mechanism used by |
|
28 the archive. </p> |
|
29 <section><title>Required background</title> <p>Before you start, you must |
|
30 understand: </p> <ul> |
|
31 <li id="GUID-099EC8EB-0A45-5FBF-9F55-B38D9C0AFCA8"><p><xref href="GUID-84B6389A-55CC-53EB-8725-65F753FD7217.dita"> Content |
|
32 Access Framework for DRM</xref> </p> </li> |
|
33 <li id="GUID-16D006BB-3D7E-5439-BFFC-727EFF82D40E"><p><xref href="GUID-B5CC77D2-5871-51D8-B359-77EFC081B423.dita">Files |
|
34 Containing Multiple Content Objects</xref> </p> </li> |
|
35 <li id="GUID-7029E2F7-A26A-5EC7-A435-0984C2CEE717"><p><xref href="GUID-B6912FE7-4C2A-5FC7-BDA8-702CA2C0214A.dita">Content |
|
36 Object Attributes</xref> </p> </li> |
|
37 </ul> </section> |
|
38 <section><title>Introduction</title> <p>Content Access Framework also allows |
|
39 applications to open archive files and read content from inside them. The |
|
40 content objects and containers inside the file can be traversed using the <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-FC40011B-32D3-328B-BB59-35BEF46A215A"><apiname>ContentAccess::CContent</apiname></xref> class. |
|
41 This class allows applications to use the content within the container files |
|
42 without needing to understand any specifics of the compression or storage |
|
43 mechanism used by the archive. See <xref href="GUID-B5CC77D2-5871-51D8-B359-77EFC081B423.dita">Files |
|
44 Containing Multiple Content Objects</xref> for more information. </p> <p>The |
|
45 following diagram is an example of a content file. The same diagram is used |
|
46 in the procedure to illustrate the implementation of Consumer API. </p> <fig id="GUID-BA86F65C-C34B-57C3-8FD5-A76C61EDF035"> |
|
47 <title> Example content file </title> |
|
48 <image href="GUID-1467745D-7C3F-52EC-8C1E-7E2F505B7313_d0e608140_href.png" placement="inline"/> |
|
49 </fig> </section> |
|
50 <section><title>Procedure</title> <ol id="GUID-FE716629-86BE-513F-82F5-89107FB41F0E"> |
|
51 <li id="GUID-BD7166E0-7D9C-5F55-9DF3-1DE17AEBB80B"><p><xref href="GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C.dita#GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C/GUID-09F7434B-318B-5084-8E8B-54FA0ED48031">Create a content object</xref>. </p> </li> |
|
52 <li id="GUID-2BADD3D3-D167-5212-942C-3A3CF4B7D25F"><p>Perform one or more |
|
53 of the following tasks as per your requirement: </p> <ul> |
|
54 <li id="GUID-8DFAF3E7-DC67-51E2-B609-85975BD6A564"><p><xref href="GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C.dita#GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C/GUID-26189931-0BE0-5BB7-98F1-9B7DF08C6C8F">List objects within a container</xref>. </p> </li> |
|
55 <li id="GUID-74B9014B-EFCA-5BFA-8E15-286E837D832C"><p><xref href="GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C.dita#GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C/GUID-03355CA5-D049-5625-9187-2E91FFAF703A">Open a container</xref>. </p> </li> |
|
56 <li id="GUID-ACC262EF-BBD6-5811-9EE3-A346FE600694"><p><xref href="GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C.dita#GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C/GUID-71C5AA3E-9C4B-5F77-B6D8-D09E00593EB8">Open the metadata specific to an agent</xref>. </p> </li> |
|
57 <li id="GUID-34F3E3F3-816A-5B92-8772-05AD72910F56"><p><xref href="GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C.dita#GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C/GUID-5B42E479-D3F1-5B2A-8B6F-4841E49E4B3D">Display content object information</xref>. </p> </li> |
|
58 <li id="GUID-5EC62609-8B8E-549A-806F-628C64FBE81B"><p><xref href="GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C.dita#GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C/GUID-20F9B6AC-F2B1-5E8E-93F2-8AE4AD0ED1F6">Retrieve the attributes of a content</xref>. </p> </li> |
|
59 <li id="GUID-C5F1A5F7-D83B-5FD1-814C-4B0E9416C815"><p><xref href="GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C.dita#GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C/GUID-8D6C9025-7409-5019-88B2-A99A8E020443">Search for a MIME type within a file</xref>. </p> </li> |
|
60 <li id="GUID-12C912EE-4195-5B3C-82C6-007E76629156"><p><xref href="GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C.dita#GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C/GUID-447A73D2-AF49-598E-865E-C2CEF1958C14">Read data from a content object</xref>. </p> </li> |
|
61 <li id="GUID-A9FB0738-754E-5879-A2F5-E88C5F4C7751"><p><xref href="GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C.dita#GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C/GUID-AAFE84D9-01AF-5F27-9BC2-064A565F3D53">Handle data corruption</xref>. </p> </li> |
|
62 <li id="GUID-E57145C0-DF25-5F32-9368-D86627E97B05"><p><xref href="GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C.dita#GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C/GUID-15A1A9B3-BB5D-5677-BFE9-47EABD4064BF">Handle errors</xref>. </p> </li> |
|
63 <li id="GUID-935D7FB6-15EB-5DFB-89A0-58C0C29E736D"><p><xref href="GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C.dita#GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C/GUID-6A50AE44-E618-5D99-B5D8-7BBA8FE7948A">Handle rights for DRM content</xref>. </p> </li> |
|
64 <li id="GUID-BEA5163A-5A5E-510B-AD36-313CC820DDBD"><p><xref href="GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C.dita#GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C/GUID-635EE5EF-469D-5FD3-9400-25DF95FD2E96">Get content object notifications</xref>. </p> </li> |
|
65 <li id="GUID-2828C1A0-8E91-5B46-88FD-09CF0C36F40B"><p><xref href="GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C.dita#GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C/GUID-DDAE0B57-B296-58E8-8220-AE5AA9BF7B8D">Close a container</xref>. </p> </li> |
|
66 </ul> </li> |
|
67 </ol> <p id="GUID-09F7434B-318B-5084-8E8B-54FA0ED48031"><b>Create a CContent |
|
68 object</b> </p> <p>The <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-FC40011B-32D3-328B-BB59-35BEF46A215A"><apiname>ContentAccess::CContent</apiname></xref> object encapsulates |
|
69 a single file. It allows an application to look at the structure of the objects |
|
70 within the file and the attributes of those objects. </p> <p>There are two |
|
71 ways to create a <xref href="GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A.dita"><apiname>CContent</apiname></xref> object. The application can specify |
|
72 the URI of the content or it can supply an open file handle, see <xref href="GUID-B5CC77D2-5871-51D8-B359-77EFC081B423.dita#GUID-B5CC77D2-5871-51D8-B359-77EFC081B423/GUID-28BE6074-E800-5320-89DD-D047F5C0FD86">Objects used to identify a content object within a file</xref>. </p> <codeblock id="GUID-AAF09718-0FF4-544F-B5B1-3202C58ABC95" xml:space="preserve">// Create a CContent with a URI |
|
73 CContent *content = CContent::NewL(uri); |
|
74 |
|
75 // Create a CContent with an existing file handle |
|
76 CContent *content = CContent::NewL(aFs, aFile);</codeblock> <p>Upon creation, <xref href="GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A.dita"><apiname>CContent</apiname></xref> selects |
|
77 the agent that handles the file. </p> <p id="GUID-26189931-0BE0-5BB7-98F1-9B7DF08C6C8F"><b>List |
|
78 objects within a container</b> </p> <p> <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-FC40011B-32D3-328B-BB59-35BEF46A215A"><apiname>ContentAccess::CContent</apiname></xref> acts |
|
79 like a cursor, only able to list the contents of one container object at any |
|
80 one time. When <xref href="GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A.dita"><apiname>CContent</apiname></xref> is first opened, it views the top-level |
|
81 container within the file. The top level container is actually the file itself. |
|
82 This top level container concept applies to all files, regardless of how many |
|
83 content or container objects are inside. </p> <p>Even a content file such |
|
84 as a jpeg image is a container, it's just that the file only has the <codeph>"DEFAULT"</codeph> object |
|
85 embedded inside. </p> <p>So, when the example file shown earlier is opened, |
|
86 the following objects can be seen by the <xref href="GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A.dita"><apiname>CContent</apiname></xref>: </p> <fig id="GUID-EC064DCF-FC5D-59AC-BF5F-378A57808A47"> |
|
87 <image href="GUID-518FC822-AF10-57E8-990E-BB03C2D6ACBE_d0e608313_href.png" placement="inline"/> |
|
88 </fig> <p>In this top level container, there is only one embedded content |
|
89 object visible (the <filepath>.jpg</filepath> file) and two embedded container |
|
90 objects. </p> <codeblock id="GUID-87F01EE6-EDEC-584B-844C-1DDB939FB5B3" xml:space="preserve">// Create an array to store the results of CContent::GetEmbeddedObjectsL() |
|
91 RStreamablePtrArray<CEmbeddedObject> myArray; |
|
92 CleanupClosePushL(myArray); |
|
93 |
|
94 // Get the embedded content objects in the current container |
|
95 content->GetEmbeddedObjectsL(myArray, EContentObject); |
|
96 |
|
97 i = myArray.Count(); // One content object |
|
98 |
|
99 // clear the contents of the array |
|
100 myArray.ResetAndDestroy(); |
|
101 |
|
102 // Get the number of container objects in the current container |
|
103 content->GetEmbeddedObjectsL(myArray, EContainerObject); |
|
104 |
|
105 i = myArray.Count(); // Two container objects |
|
106 |
|
107 // clear the contents of the array |
|
108 myArray->ResetAndDestroy();</codeblock> <p id="GUID-03355CA5-D049-5625-9187-2E91FFAF703A"><b>Open |
|
109 a container</b> </p> <p>To investigate the objects inside a container, <xref href="GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A.dita"><apiname>CContent</apiname></xref> must |
|
110 first open the container. This changes <xref href="GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A.dita"><apiname>CContent</apiname></xref>'s focus |
|
111 from the current container to the container specified in the <xref href="GUID-FC40011B-32D3-328B-BB59-35BEF46A215A.dita#GUID-FC40011B-32D3-328B-BB59-35BEF46A215A/GUID-BB793B8F-1A01-3169-99E6-4630E9B5581C"><apiname>ContentAccess::CContent::OpenContainer()</apiname></xref> function. </p> <p><i>Open |
|
112 container 1 from the top level of the file</i> </p> <codeblock id="GUID-7239CC22-292D-54BD-A50B-76413A887AD7" xml:space="preserve">// Get the container objects in the top level of the file |
|
113 content->GetEmbeddedObjects(myArray, EContainerObject); |
|
114 |
|
115 // Find the Unique Id of the first container |
|
116 TPtrC UniqueId = myArray[0]->UniqueId() |
|
117 |
|
118 // Open the first container |
|
119 content->OpenContainer(UniqueId);</codeblock> <p>Now <xref href="GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A.dita"><apiname>CContent</apiname></xref> can |
|
120 see the contents of Container 1: </p> <fig id="GUID-2A67C29A-FBF3-553E-B653-462F5128B2F4"> |
|
121 <image href="GUID-DC7E3634-9762-542F-BDAE-AC1F2D03F55D_d0e608362_href.png" placement="inline"/> |
|
122 </fig> <p>At this point, listing the objects that <xref href="GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A.dita"><apiname>CContent</apiname></xref> can |
|
123 see gives six MP3 files and one container object. </p> <codeblock id="GUID-F1A7C149-9AB1-5DD2-BE20-280431DBAF40" xml:space="preserve">// Get the embedded content objects in the current container |
|
124 content->GetEmbeddedObjectsL(myArray, EContentObject); |
|
125 |
|
126 i = myArray.Count(); // Six content objects |
|
127 myArray.ResetAndDestroy(); |
|
128 |
|
129 // Get the number of container objects in the current container |
|
130 content->GetEmbeddedObjectsL(myArray, EContainerObject); |
|
131 |
|
132 i = myArray.Count(); // One container object |
|
133 myArray.ResetAndDestroy();</codeblock> <p> <b> Note: </b> The same process |
|
134 can be followed again to see the contents of Container 1.1. </p> <p id="GUID-71C5AA3E-9C4B-5F77-B6D8-D09E00593EB8"><b>Open |
|
135 the metadata specific to an agent</b> </p> <p>Some agents may expose metadata |
|
136 so they can be read using a <xref href="GUID-136D0282-4C73-33E9-B9D4-9CE92A33BF75.dita"><apiname>CData</apiname></xref> object. The format of |
|
137 these meta-data objects is not specified by the Content Access Framework but |
|
138 can be useful for applications familiar with the agent to read meta data this |
|
139 way. </p> <p> <codeph>CData</codeph> objects for agent specific metadata can |
|
140 be opened in the same way content objects are opened, using the <xref href="GUID-FC40011B-32D3-328B-BB59-35BEF46A215A.dita#GUID-FC40011B-32D3-328B-BB59-35BEF46A215A/GUID-32BA0116-1D7F-31B1-B80E-32E1F55803C3"><apiname>ContentAccess::CContent::OpenContentL()</apiname></xref> function. </p> <codeblock id="GUID-62EB232A-E9D6-5151-A69B-87CA26E97A9D" xml:space="preserve">// Create an array to store the embedded objects |
|
141 ... |
|
142 |
|
143 // Get the embedded "Agent Specific" objects in the current container |
|
144 content->GetEmbeddedObjectsL(myArray, EAgentSpecificObject); |
|
145 |
|
146 // Get the unique Id of the first meta-data object |
|
147 TPtrC uniqueId = myArray[0]->UniqueId(); |
|
148 |
|
149 // create a CData object to read the meta data |
|
150 CData *myMetaData = content->OpenContent(EPeek, uniqueId);</codeblock> <p id="GUID-5B42E479-D3F1-5B2A-8B6F-4841E49E4B3D"><b>Display content object information</b> </p> <p>The <xref href="GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A.dita#GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A/GUID-79E768C6-D63E-303F-943C-022F5A04AB08"><apiname>CContent::DisplayInfoL()</apiname></xref> function |
|
151 allows the application to display file information, such as last modification |
|
152 date and DRM rights information. </p> <codeblock id="GUID-62A01A68-2479-515C-B74D-C48721870F1D" xml:space="preserve">... |
|
153 content->DisplayInfoL(TDisplayInfo aInfo); |
|
154 ... |
|
155 </codeblock> <p id="GUID-20F9B6AC-F2B1-5E8E-93F2-8AE4AD0ED1F6"><b>Retrieve |
|
156 the attributes of a content</b> </p> <p>Content and container objects have |
|
157 properties or attributes associated with it. Applications can retrieve single |
|
158 or mulitple attributes using the <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-4FA0F8A6-7F9A-3AE6-BDEE-B3C8A53B0207"><apiname>ContentAccess::TAttributeCAF</apiname></xref> enumeration |
|
159 and the <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-BC242813-E0F0-3DFE-AF97-6BE808D570DE"><apiname>ContentAccess::TStringAttribute</apiname></xref> enumeration. See <xref href="GUID-B6912FE7-4C2A-5FC7-BDA8-702CA2C0214A.dita">Content Object Attributes</xref> for |
|
160 details on implementing different methods of retrieving attributes. </p> <p>The |
|
161 following example finds the author attribute of a content object. </p> <codeblock id="GUID-5FB7E26E-E8CF-5A10-8B22-06FA45A69721" xml:space="preserve">// define a buffer to store the attribute value string |
|
162 TBuf <100> buf; |
|
163 |
|
164 // retrieve the attribute |
|
165 err = content->GetAttribute(EAuthor, buf, uniqueId); |
|
166 |
|
167 // Display the author's name on screen |
|
168 DisplayAuthor(buf); |
|
169 </codeblock> <p id="GUID-8D6C9025-7409-5019-88B2-A99A8E020443"><b>Search for |
|
170 a MIME type within a file</b> </p> <p>If an application wants to find all |
|
171 the content with a particular MIME type within a file, it must use <xref href="GUID-FC40011B-32D3-328B-BB59-35BEF46A215A.dita#GUID-FC40011B-32D3-328B-BB59-35BEF46A215A/GUID-FA4BB868-3297-39F0-BAB8-C4BF4F5A2B60"><apiname>ContentAccess::CContent::Search()</apiname></xref>. |
|
172 This function produces a list of all content objects with the specified MIME |
|
173 type that are stored under the current container. </p> <codeblock id="GUID-BD3FEDFD-DA3E-5491-BF97-60CFC9252935" xml:space="preserve">// Create an array for storing the result of the search |
|
174 RStreamablePtrArray<CEmbeddedObject> myArray; |
|
175 |
|
176 // Find how many MP3 files are in Container 1 |
|
177 TInt numMp3 = content->Search(myArray, _L("mpeg/audio"), EFalse);</codeblock> <p id="GUID-447A73D2-AF49-598E-865E-C2CEF1958C14"><b>Read data from a content |
|
178 object</b> </p> <p>The functions described earlier can be used to locate a |
|
179 particular content object within a file. <xref href="GUID-FC40011B-32D3-328B-BB59-35BEF46A215A.dita#GUID-FC40011B-32D3-328B-BB59-35BEF46A215A/GUID-32BA0116-1D7F-31B1-B80E-32E1F55803C3"><apiname>ContentAccess::CContent::OpenContentL()</apiname></xref> can |
|
180 be used to read the content object. The <codeph>UniqueId</codeph> parameter |
|
181 can be used to identify a particular object within the file. </p> <p>The call |
|
182 to <xref href="GUID-FC40011B-32D3-328B-BB59-35BEF46A215A.dita#GUID-FC40011B-32D3-328B-BB59-35BEF46A215A/GUID-32BA0116-1D7F-31B1-B80E-32E1F55803C3"><apiname>ContentAccess::CContent::OpenContentL()</apiname></xref> leaves if the |
|
183 intent is not permitted. This could occur if the file is DRM-protected but |
|
184 no rights are present. </p> <p>If the file is DRM protected and the call to <xref href="GUID-63702251-43C2-3A2C-B884-A865BB539B5C.dita"><apiname>OpenContentL()</apiname></xref> succeeds, |
|
185 the rights are not consumed at this point. CAF just checks that it is possible |
|
186 to use the content. </p> <codeblock id="GUID-DCA8F01C-9657-5F54-881E-0A297DD652AC" xml:space="preserve">// Open the content object specified by uniqueId with the EPlay intent |
|
187 CData* data = content->OpenContentL(EPlay, uniqueId);</codeblock> <p>If the |
|
188 application already knows the URI and unique ID of the content object it wants |
|
189 to read from, it can create a <codeph>CData</codeph> object directly. </p> <codeblock id="GUID-09916FE1-A7A6-5012-8057-ACC0BFB49EDC" xml:space="preserve">CData* data = CData::NewL(TVirtualPathPtr(uri, uniqueId), EPlay, EContentShareReadOnly);</codeblock> <p>Once the <codeph>CData</codeph> object has been constructed, it allows |
|
190 the content object to be used as if it were a standalone unprotected file. |
|
191 The client must call <xref href="GUID-B54C8391-FE69-324C-AC0A-1E88C2555F00.dita#GUID-B54C8391-FE69-324C-AC0A-1E88C2555F00/GUID-3E5B2A86-A06B-3710-99C9-FA205E99088F"><apiname>ContentAccess::CData::ExecuteIntent()</apiname></xref> when |
|
192 the rights must be consumed. If the file is not DRM-protected, the call is |
|
193 ignored by the agent handling the file. </p> <codeblock id="GUID-81167DB6-CD1B-5F19-88D2-ED6D5C66B5AA" xml:space="preserve">TBuf8 <256> buf; |
|
194 data->ExecuteIntent(EPlay); |
|
195 data->Seek(ESEEK_START,SomePosition); |
|
196 data->Read(buf);</codeblock> <p>There are several overloaded versions of the <xref href="GUID-B54C8391-FE69-324C-AC0A-1E88C2555F00.dita#GUID-B54C8391-FE69-324C-AC0A-1E88C2555F00/GUID-B6146300-5578-39D2-B7E2-19309B76A7F6"><apiname>ContentAccess::CData::Read()</apiname></xref> function. |
|
197 Only one is illustrated above for example purposes. </p> <p id="GUID-AAFE84D9-01AF-5F27-9BC2-064A565F3D53"><b>Handle |
|
198 data corruption</b> </p> <p>When consuming content it is possible that the |
|
199 content data and rights data can be corrupted. This may be due to various |
|
200 reasons including file or disk corruption, transmission errors and so on. </p> <p>If |
|
201 an agent detects corruption in a content object or in a rights object, it |
|
202 ends the current DRM operation. The <codeph>KErrCACorruptContent</codeph>, <codeph>KErrCACorruptRights</codeph> or <codeph>KErrCorrupt</codeph> error |
|
203 code is sent to clients, depending on the type of corruption detected and |
|
204 how the client chooses to handle it. </p> <p> <b>Note:</b> It is recommended |
|
205 that clients be designed to handle such an error if received, as it can usually |
|
206 be considered a fatal error. </p> <codeblock id="GUID-24C1BC9E-786E-5C1F-AA27-839B3DC9369F" xml:space="preserve">// Create a CData object to read the content |
|
207 ... |
|
208 |
|
209 TRAP(err, data = content->OpenContentLC(EDisplay)); |
|
210 |
|
211 if (err != KErrNone) |
|
212 { |
|
213 if (err == KErrCACorruptRights) |
|
214 { |
|
215 //Agent may have performed some error handling. |
|
216 //Client may need to perform some client specific operations(e.g. cleanup). |
|
217 } |
|
218 else if (err == KErrCorrupt) |
|
219 { |
|
220 DisplayErrorMsg('Unable to decode rights because it is corrupt!'); |
|
221 } |
|
222 else if (err == ...) |
|
223 ... |
|
224 } |
|
225 ... |
|
226 </codeblock> <p id="GUID-15A1A9B3-BB5D-5677-BFE9-47EABD4064BF"><b>Handle errors</b> </p> <p>Agents |
|
227 display the errors on screen when they occur. Once the error has been acknowledged |
|
228 by the user, the agent returns the error code to the client application. If |
|
229 a client application does not want errors displayed on screen, it can request |
|
230 to disable the agent UI using the <xref href="GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A.dita#GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A/GUID-4F452F1F-FFDA-34F4-9625-0A047CF44DE1"><apiname>CContent::SetProperty()</apiname></xref> function. </p> <codeblock id="GUID-20598B16-CC87-5BE1-8B7D-CF612A2150FB" xml:space="preserve">// Disable UI |
|
231 content->SetProperty(EAgentPropertyAgentUI , 0); |
|
232 </codeblock> <p>Some agents may present confirmation dialogs to the user before |
|
233 allowing them to perform certain operations. For example, when a user inadvertently |
|
234 tries to delete a DRM-protected file. The agent can present a dialog asking |
|
235 "are you sure?". The agent can then return the outcome of the delete to the |
|
236 application, that is <codeph>KErrCancel</codeph>, if the user presses cancel. |
|
237 The <xref href="GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A.dita#GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A/GUID-4F452F1F-FFDA-34F4-9625-0A047CF44DE1"><apiname>CContent::SetProperty()</apiname></xref> function can also be used to |
|
238 disable the confirmation dialogs. </p> <p id="GUID-6A50AE44-E618-5D99-B5D8-7BBA8FE7948A"><b>Handle |
|
239 rights for DRM content</b> </p> <p>There are two functions available that |
|
240 give the application some control over the rights: </p> <p><i>Request rights</i> </p> <p> <xref href="GUID-FC40011B-32D3-328B-BB59-35BEF46A215A.dita#GUID-FC40011B-32D3-328B-BB59-35BEF46A215A/GUID-BF3DA6BD-A779-3BD8-B668-DB8E900F9053"><apiname> ContentAccess::CContent::RequestRights()</apiname></xref> allows the application to ask the agent to undertake whatever steps are |
|
241 necessary to obtain rights for the given content object. Some agents may not |
|
242 support this mechanism, in which case they returns <codeph>KErrCANotSupported</codeph>. </p> <p>The |
|
243 request rights call includes a <codeph>TRequestStatus</codeph> parameter, |
|
244 which allows the application to be notified of the outcome of the rights request. </p> <codeblock id="GUID-FEA60E64-1735-5D3D-8D14-6BA3E6F8A54E" xml:space="preserve">content->RequestRights(status, uniqueId);</codeblock> <p><i>Display |
|
245 information</i></p> <p> <xref href="GUID-FC40011B-32D3-328B-BB59-35BEF46A215A.dita#GUID-FC40011B-32D3-328B-BB59-35BEF46A215A/GUID-6613813A-5621-3F0F-B64F-DA2E1F89D7E7"><apiname>ContentAccess::CContent::DisplayInfoL()</apiname></xref> allows |
|
246 the application to ask the agent to display the file and/or rights information |
|
247 for the given content object. The call returns when the display is dismissed. </p> <p>Some |
|
248 agents may not support this mechanism, in which case they return <codeph>KErrCANotSupported</codeph>. </p> <codeblock id="GUID-8B96985A-4810-5CE1-9561-0C8BC5D725C0" xml:space="preserve">content->DisplayInfoL(EFileProperties, uniqueId);</codeblock> <p id="GUID-635EE5EF-469D-5FD3-9400-25DF95FD2E96"><b>Get content object notifications</b> </p> <p>The <xref href="GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A.dita"><apiname>CContent</apiname></xref> interface |
|
249 supports notification requests for content objects within files. The events |
|
250 for which an application can request notification are given by the enumeration <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-20035389-F839-3ACF-B892-B6A58A13460A"><apiname>ContentAccess::TEventMask</apiname></xref>. </p> <p>The |
|
251 following example requests and cancels notification for rights becoming available: </p> <codeblock id="GUID-81C47EF6-AF59-59AC-B07F-D190ABE89973" xml:space="preserve">// Request notification when rights become available for a particular content object |
|
252 content->NotifyStatusChange(ERightsAvailable, status, uniqueId); |
|
253 |
|
254 // Cancel notification request |
|
255 content->CancelNotifyStatusChange(status, uniqueId);</codeblock> <p id="GUID-DDAE0B57-B296-58E8-8220-AE5AA9BF7B8D"><b>Close |
|
256 a container</b> </p> <p>To close a container, use the <xref href="GUID-FC40011B-32D3-328B-BB59-35BEF46A215A.dita#GUID-FC40011B-32D3-328B-BB59-35BEF46A215A/GUID-E4CAB325-A0BC-3A43-A1CD-F099B478B188"><apiname>ContentAccess::CContent::CloseContainer()</apiname></xref> function. </p> <p>For |
|
257 example, Container 1.1 is closed and Container 1 is still open: </p> <codeblock id="GUID-FDDCBB26-6FA6-5B1C-87EA-EE32182A97C1" xml:space="preserve">//Close Container 1.1 |
|
258 content->CloseContainer(); |
|
259 |
|
260 // Get the embedded content objects in the current container |
|
261 content->GetEmbeddedObjectsL(myArray, EContentObject); |
|
262 i = myArray.Count(); // Six content objects |
|
263 myArray.ResetAndDestroy(); |
|
264 |
|
265 // Get the number of container objects in the current container |
|
266 content->GetEmbeddedObjectsL(myArray, EContainerObject); |
|
267 i = myArray.Count(); // One container object |
|
268 myArray.ResetAndDestroy();</codeblock> <fig id="GUID-F3A1B237-A07C-5AE7-82F1-5DAA3BA65553"> |
|
269 <image href="GUID-DC7E3634-9762-542F-BDAE-AC1F2D03F55D_d0e608670_href.png" placement="inline"/> |
|
270 </fig> </section> |
|
271 </conbody></concept> |