|
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-B5CC77D2-5871-51D8-B359-77EFC081B423" xml:lang="en"><title>Files |
|
13 Containing Multiple Content Objects</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>Content Access Framework provides a generic mechanism for exploring files |
|
15 that contain multiple content objects. These files are often referred to as |
|
16 archive files. This can be <filepath>.ZIP</filepath> compression archive or |
|
17 a DRM protected archive, such as an OMA <filepath>.DCF</filepath> file. An |
|
18 application can explore the content objects inside a file 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. </p> |
|
19 <section><title>Structure of a file containing multiple content objects</title> <p>An |
|
20 archive file can have content objects and meta-data or information associated |
|
21 with the content. This meta-data can include information, such as the MIME |
|
22 type of the content, the encryption algorithm, the compressed size of the |
|
23 content. This information can be retrieved from the attributes related to |
|
24 a content object, see <xref href="GUID-B6912FE7-4C2A-5FC7-BDA8-702CA2C0214A.dita">Content |
|
25 Object Attributes</xref>. </p> <p>The content and meta-data may also be arranged |
|
26 in a hierachy with container objects grouping content objects together. A |
|
27 typical archive can have a complex structure as the example shown below: </p> <fig id="GUID-13E44820-5D67-580F-BC0D-26A935EB1F72"> |
|
28 <image href="GUID-4B7410B2-849B-5E89-97BF-E06613F600CB_d0e607160_href.png" placement="inline"/> |
|
29 </fig> <p>In this scenario, the file itself can be considered as the top level |
|
30 container. All other content, containers and meta-data are nested inside. |
|
31 In an archive file, applications can quickly search for the content objects |
|
32 they are interested in by using <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>, |
|
33 see <xref href="GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C.dita">Consumer API Tutorial</xref>. </p> </section> |
|
34 <section id="GUID-34F8F3F7-B497-5BBE-B282-33DF7DB0D560"><title>Identifying |
|
35 a content object within a file</title> <p>Archive files containing several |
|
36 content objects cannot be referred to using just the URI of the file. The |
|
37 Content Access Framework uses a concept of virtual paths to identify content |
|
38 objects within a file. The virtual path is a combination of the file URI and |
|
39 a unique identifier supplied by the agent: </p> <ul> |
|
40 <li id="GUID-CA623AF7-3752-5369-BFE2-1CDADC963A26"><p> <codeph>URI</codeph>: |
|
41 the location of the file. </p> </li> |
|
42 <li id="GUID-9455FFE0-129D-5EDB-B7E9-BC4D907DE53C"><p> <codeph>UniqueId</codeph>: |
|
43 the content object inside the file. </p> </li> |
|
44 </ul> <p>A content file is only handled by the agent that recognises it. The |
|
45 unique identifier is not required to be decoded by anyone other than the agent |
|
46 that generated it, so the format is left for the agent to implement as it |
|
47 sees fit. For instance, an OMA DRM agent may put the Content ID (CID) in the <codeph>UniqueId</codeph> field. </p> <p>The |
|
48 only constraint is that the <codeph>UniqueId</codeph> must be unique within |
|
49 the file. An application must be able to directly reference a content object |
|
50 just using the <codeph>UniqueId</codeph>. </p> </section> |
|
51 <section id="GUID-28BE6074-E800-5320-89DD-D047F5C0FD86"><title>Objects used |
|
52 to identify a content object within a file</title> <p><b>Virtual path pointer |
|
53 objects on the stack </b> </p> <p>The <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-70925BDF-36EF-3705-9C95-9EE211543517"><apiname>ContentAccess::TVirtualPathPtr</apiname></xref> is |
|
54 used to point to two descriptors holding the URI of a file and the <codeph>UniqueId</codeph> of |
|
55 a content object within the file. It can also be used to point to another <codeph>TVirtualPathPtr</codeph>. |
|
56 Since it is only a pointer, the original descriptors used to initalise the <codeph>TVirtualPathPtr</codeph> must |
|
57 not be destroyed or modified while the <codeph>TVirtualPathPtr</codeph> is |
|
58 still in use. </p> <p><b>Virtual path objects on the heap </b> </p> <p>The <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-D56FD380-1335-33BB-B42E-6C1911274B06"><apiname>ContentAccess::CVirtualPath</apiname></xref> class |
|
59 stores the file URI and content object <codeph>UniqueId</codeph> in its own |
|
60 descriptors. There is a cast operator that allows the <codeph>CVirtualPath</codeph> to |
|
61 be used as if it were a <codeph>TVirtualPathPtr</codeph> . </p> <p><b>Examples </b> </p> <codeblock id="GUID-C2E6E29D-C2DF-5D7C-B262-B979FC91A1A8" xml:space="preserve">// Open a CContent object to browse the objects inside a file |
|
62 CContent *c = CContent::NewL(_L("C:\file.dcf")); |
|
63 CleanupStack::PushL(c); |
|
64 |
|
65 // Create an array to store the embedded objects |
|
66 RStreamablePtrArray<CEmbeddedObject> myArray; |
|
67 |
|
68 // Get an array of the embedded objects within the current container in the file |
|
69 c->GetEmbeddedObjects(myArray); |
|
70 |
|
71 // If necessary we can get a "mangled" version of the URI that |
|
72 // references the particular object within the file |
|
73 // i.e. "C:\file.dcf\\OBJECT1" |
|
74 |
|
75 CData* data = iContent->OpenContentL(EPlay,myArray[0]->UniqueId()); |
|
76 |
|
77 TFileName uri; |
|
78 data->GetStringAttribute(EPreviewURI,uri); |
|
79 . |
|
80 . |
|
81 . |
|
82 // Now we can use our TPtrC later to create a TVirtualPath object from a URI |
|
83 TVirtualPathPtr aPtr = aURI; |
|
84 |
|
85 // print the file URI "C:\file.dcf" |
|
86 printf(aPtr.URI()); |
|
87 |
|
88 // print the content object's UniqueId "OBJECT1" |
|
89 printf(aPtr.UniqueId()); |
|
90 |
|
91 // Create a copy of the virtual path on the heap so we don't have any ownership problems |
|
92 CVirtualPath *myVirtualpath = CVirtualPath::NewL(aPtr) |
|
93 |
|
94 // Can now delete the CContent object without losing our VirtualPath |
|
95 CleanupStack::PopAndDestroy(c);</codeblock> </section> |
|
96 <section><title>Special cases for the UniqueId field</title> <p><b>KNullDesC16() |
|
97 - "" </b> </p> <p>A zero length <codeph>UniqueId</codeph> is used to refer |
|
98 to the entire file. If a file is opened this way, no translation of the contents |
|
99 is performed. The ability to open the file with no translation is required |
|
100 for example to attach the file to an outgoing message. As with any other function |
|
101 in CAF, access to the file is at the agent's discretion. </p> <p><b>KDefaultContentObject() |
|
102 - "DEFAULT" </b> </p> <p>Allows an application to refer to the default content |
|
103 object within a file. In the case of an unprotected file handled by the <codeph>F32Agent</codeph>, |
|
104 it is the entire file, the same as if the <codeph>UniqueId</codeph> <codeph>""</codeph> was |
|
105 used. Other agents, particularly those with a single content object embedded |
|
106 within the file, use <codeph>"DEFAULT"</codeph> to refer to their only content |
|
107 object. </p> <p>Even though the <codeph>DEFAULT</codeph> content object is |
|
108 supported, it is recommended that agents always use <codeph>CContent</codeph> to |
|
109 enumerate the objects within the file. </p> </section> |
|
110 </conbody></concept> |