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