1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of the License "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // An application can explore the content objects inside a file using the <code>ContentAccess::CContent</code> class. |
|
15 // <hr> |
|
16 // The Content Access Framework provides a generic mechanism for exploring files that contain multiple |
|
17 // content objects. These files are often referred to as archive files. This could |
|
18 // be anything from a .ZIP compression archive to a DRM protected archive such as an OMA .DCF file. |
|
19 // Inside an archive file, and in addition to the content objects, there will be meta-data or information |
|
20 // associated with the content. This meta-data could include information such as the MIME type of the content, |
|
21 // encryption algorithm, compressed size of the content etc.. This information can be retrieved from the attributes |
|
22 // The content and meta-data may also be arranged in a heirachy with container objects grouping |
|
23 // content objects together. A typical archive could have a complex structure like the example shown below: |
|
24 // In this situation the file itself can be considered as the top level container. All other content, containers and |
|
25 // meta-data are nested inside. |
|
26 // In an archive file applications can quickly search for the content objects they are interested in by using |
|
27 // <code>ContentAccess::CContent::Search()</code>. |
|
28 // <hr> |
|
29 // Archive files containing several content objects cannot be referred to using just the URI of the file. The Content Access |
|
30 // Framework uses a concept of virtual paths to identify content objects within a file. The virtual path is a combination |
|
31 // of the file URI and a unique identifier supplied by the agent: |
|
32 // A content file is only ever handled by the agent that recognises it. The unique identifier will never need to be |
|
33 // decoded by anyone other that the agent that generated it, so the format is left for the agent to implement as it sees |
|
34 // fit. For instance an OMA DRM agent may put the Content ID (CID) in the \c UniqueId field. |
|
35 // The only constraint is that the \c UniqueId must be unique within the file. An application must be able to directly |
|
36 // reference a content object just using the <code>UniqueId</code>. |
|
37 // <hr> |
|
38 // <b> Virtual Path pointer objects on the Stack </b> |
|
39 // The <code>ContentAccess::TVirtualPathPtr</code> is used to point to two descriptors holding the URI |
|
40 // of a file and the <code>UniqueId</code> of a content object within the file. It can also be used to |
|
41 // point to another <code>TVirtualPathPtr</code>. Since it is only a pointer, the original descriptors |
|
42 // used to initalise the <code>TVirtualPathPtr</code> should not be destroyed or modified while the |
|
43 // <code>TVirtualPathPtr</code> is still in use. |
|
44 // <b> Virtual Path objects on the heap </b> |
|
45 // The <code>ContentAccess::CVirtualPath</code> class stores the file URI and content object <code>UniqueId</code> in its own |
|
46 // descriptors. There is a cast operator that allows the <code>CVirtualPath</code> to be used as |
|
47 // if it were a <code>TVirtualPathPtr</code>. |
|
48 // <b> Examples </b> |
|
49 // // Open a CContent object to browse the objects inside a file |
|
50 // CContent *c = CContent::NewL(_L("C:\file.dcf")); |
|
51 // CleanupStack::PushL(c); |
|
52 // // Create an array to store the embedded objects |
|
53 // RStreamablePtrArray<CEmbeddedObject> myArray; |
|
54 // CleanupClosePushL(myArray); |
|
55 // // Get an array of the embedded objects within the current container in the file |
|
56 // c->GetEmbeddedObjectsL(myArray); |
|
57 // // If necessary we can get a "mangled" version of the URI that |
|
58 // // references the particular object within the file |
|
59 // // ie. "C:\file.dcf\\OBJECT1" |
|
60 // TPtrC aURI = *myArray[0]; |
|
61 // // Now we can use our TPtrC later to create a TVirtualPath object from a URI |
|
62 // TVirtualPathPtr aPtr = aURI; |
|
63 // // print the file URI "C:\file.dcf" |
|
64 // printf(aPtr.URI()); |
|
65 // // print the content object's UniqueId "OBJECT1" |
|
66 // printf(aPtr.UniqueId()); |
|
67 // // Create a copy of aVirtualPath on the heap so we don't have any ownership problems |
|
68 // CVirtualPath *myVirtualpath = CVirtualPath::NewL(aPtr); |
|
69 // // Can now delete the CContent object without loosing our VirtualPath |
|
70 // CleanupStack::PopAndDestroy(2); // c, myArray |
|
71 // <hr> |
|
72 // <b><code>KNullDesC16() - ""</code></b> |
|
73 // A zero length \c UniqueId is used to refer to the entire file. If a file is opened this way no translation of the contents will be |
|
74 // performed. The ability to open the file with no translation is required for example to attach the file to an outgoing message. |
|
75 // As with any other function in CAF access to the file is at the agents discretion. |
|
76 // <b><code>KDefaultContentObject() - "DEFAULT"</code></b> |
|
77 // Allows an application to refer to the default content object within a file. In the case of an unprotected file handled |
|
78 // by the \c F32Agent this will be the entire file, the same as if the <code>UniqueId ""</code> was used. Other agents, particularly those |
|
79 // with a single content object embedded within the file, use <code>"DEFAULT"</code> to refer to their only content object. |
|
80 // Even though the DEFAULT content object is supported, it is recommended that agents always use \c CContent to enumerate the |
|
81 // objects within the file. |
|
82 // <hr> |
|
83 // |
|
84 // |
|
85 |
|
86 /** |
|
87 @page FileOverview Files containing multiple content objects |
|
88 - @ref FileOverviewDescription |
|
89 - @ref VirtualPaths |
|
90 - @ref VirtualPathObjects |
|
91 - @ref SpecialUniqueIds |
|
92 @section FileOverviewDescription Structure of a file containing multiple content objects |
|
93 related to a content object, see @ref ContentAttributes "Content Object Attributes". |
|
94 @image html "multiple DRM file2.gif" |
|
95 @section VirtualPaths Identifying a content object within a File |
|
96 @li \c URI - The location of the file |
|
97 @li \c UniqueId - The content object inside the file. |
|
98 @section VirtualPathObjects Objects used to identify a content object within a File |
|
99 @code |
|
100 @endcode |
|
101 @section SpecialUniqueIds Special Cases for the UniqueId field |
|
102 */ |
|