os/security/contentmgmt/contentaccessfwfordrm/engineering/dox/NavigatingArchiveFiles.dox
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/security/contentmgmt/contentaccessfwfordrm/engineering/dox/NavigatingArchiveFiles.dox Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,102 @@
1.4 +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// An application can explore the content objects inside a file using the <code>ContentAccess::CContent</code> class.
1.18 +// <hr>
1.19 +// The Content Access Framework provides a generic mechanism for exploring files that contain multiple
1.20 +// content objects. These files are often referred to as archive files. This could
1.21 +// be anything from a .ZIP compression archive to a DRM protected archive such as an OMA .DCF file.
1.22 +// Inside an archive file, and in addition to the content objects, there will be meta-data or information
1.23 +// associated with the content. This meta-data could include information such as the MIME type of the content,
1.24 +// encryption algorithm, compressed size of the content etc.. This information can be retrieved from the attributes
1.25 +// The content and meta-data may also be arranged in a heirachy with container objects grouping
1.26 +// content objects together. A typical archive could have a complex structure like the example shown below:
1.27 +// In this situation the file itself can be considered as the top level container. All other content, containers and
1.28 +// meta-data are nested inside.
1.29 +// In an archive file applications can quickly search for the content objects they are interested in by using
1.30 +// <code>ContentAccess::CContent::Search()</code>.
1.31 +// <hr>
1.32 +// Archive files containing several content objects cannot be referred to using just the URI of the file. The Content Access
1.33 +// Framework uses a concept of virtual paths to identify content objects within a file. The virtual path is a combination
1.34 +// of the file URI and a unique identifier supplied by the agent:
1.35 +// A content file is only ever handled by the agent that recognises it. The unique identifier will never need to be
1.36 +// decoded by anyone other that the agent that generated it, so the format is left for the agent to implement as it sees
1.37 +// fit. For instance an OMA DRM agent may put the Content ID (CID) in the \c UniqueId field.
1.38 +// The only constraint is that the \c UniqueId must be unique within the file. An application must be able to directly
1.39 +// reference a content object just using the <code>UniqueId</code>.
1.40 +// <hr>
1.41 +// <b> Virtual Path pointer objects on the Stack </b>
1.42 +// The <code>ContentAccess::TVirtualPathPtr</code> is used to point to two descriptors holding the URI
1.43 +// of a file and the <code>UniqueId</code> of a content object within the file. It can also be used to
1.44 +// point to another <code>TVirtualPathPtr</code>. Since it is only a pointer, the original descriptors
1.45 +// used to initalise the <code>TVirtualPathPtr</code> should not be destroyed or modified while the
1.46 +// <code>TVirtualPathPtr</code> is still in use.
1.47 +// <b> Virtual Path objects on the heap </b>
1.48 +// The <code>ContentAccess::CVirtualPath</code> class stores the file URI and content object <code>UniqueId</code> in its own
1.49 +// descriptors. There is a cast operator that allows the <code>CVirtualPath</code> to be used as
1.50 +// if it were a <code>TVirtualPathPtr</code>.
1.51 +// <b> Examples </b>
1.52 +// // Open a CContent object to browse the objects inside a file
1.53 +// CContent *c = CContent::NewL(_L("C:\file.dcf"));
1.54 +// CleanupStack::PushL(c);
1.55 +// // Create an array to store the embedded objects
1.56 +// RStreamablePtrArray<CEmbeddedObject> myArray;
1.57 +// CleanupClosePushL(myArray);
1.58 +// // Get an array of the embedded objects within the current container in the file
1.59 +// c->GetEmbeddedObjectsL(myArray);
1.60 +// // If necessary we can get a "mangled" version of the URI that
1.61 +// // references the particular object within the file
1.62 +// // ie. "C:\file.dcf\\OBJECT1"
1.63 +// TPtrC aURI = *myArray[0];
1.64 +// // Now we can use our TPtrC later to create a TVirtualPath object from a URI
1.65 +// TVirtualPathPtr aPtr = aURI;
1.66 +// // print the file URI "C:\file.dcf"
1.67 +// printf(aPtr.URI());
1.68 +// // print the content object's UniqueId "OBJECT1"
1.69 +// printf(aPtr.UniqueId());
1.70 +// // Create a copy of aVirtualPath on the heap so we don't have any ownership problems
1.71 +// CVirtualPath *myVirtualpath = CVirtualPath::NewL(aPtr);
1.72 +// // Can now delete the CContent object without loosing our VirtualPath
1.73 +// CleanupStack::PopAndDestroy(2); // c, myArray
1.74 +// <hr>
1.75 +// <b><code>KNullDesC16() - ""</code></b>
1.76 +// 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
1.77 +// performed. The ability to open the file with no translation is required for example to attach the file to an outgoing message.
1.78 +// As with any other function in CAF access to the file is at the agents discretion.
1.79 +// <b><code>KDefaultContentObject() - "DEFAULT"</code></b>
1.80 +// Allows an application to refer to the default content object within a file. In the case of an unprotected file handled
1.81 +// by the \c F32Agent this will be the entire file, the same as if the <code>UniqueId ""</code> was used. Other agents, particularly those
1.82 +// with a single content object embedded within the file, use <code>"DEFAULT"</code> to refer to their only content object.
1.83 +// Even though the DEFAULT content object is supported, it is recommended that agents always use \c CContent to enumerate the
1.84 +// objects within the file.
1.85 +// <hr>
1.86 +//
1.87 +//
1.88 +
1.89 +/**
1.90 + @page FileOverview Files containing multiple content objects
1.91 + - @ref FileOverviewDescription
1.92 + - @ref VirtualPaths
1.93 + - @ref VirtualPathObjects
1.94 + - @ref SpecialUniqueIds
1.95 + @section FileOverviewDescription Structure of a file containing multiple content objects
1.96 + related to a content object, see @ref ContentAttributes "Content Object Attributes".
1.97 + @image html "multiple DRM file2.gif"
1.98 + @section VirtualPaths Identifying a content object within a File
1.99 + @li \c URI - The location of the file
1.100 + @li \c UniqueId - The content object inside the file.
1.101 + @section VirtualPathObjects Objects used to identify a content object within a File
1.102 + @code
1.103 + @endcode
1.104 + @section SpecialUniqueIds Special Cases for the UniqueId field
1.105 +*/