sl@0: // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of the License "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // An application can explore the content objects inside a file using the <code>ContentAccess::CContent</code> class.
sl@0: // <hr>
sl@0: // The Content Access Framework provides a generic mechanism for exploring files that contain multiple
sl@0: // content objects. These files are often referred to as archive files. This could
sl@0: // be anything from a .ZIP compression archive to a DRM protected archive such as an OMA .DCF file.
sl@0: // Inside an archive file, and in addition to the content objects, there will be meta-data or information 
sl@0: // associated with the content. This meta-data could include information such as the MIME type of the content, 
sl@0: // encryption algorithm, compressed size of the content etc.. This information can be retrieved from the attributes
sl@0: // The content and meta-data may also be arranged in a heirachy with container objects grouping 
sl@0: // content objects together. A typical archive could have a complex structure like the example shown below:
sl@0: // In this situation the file itself can be considered as the top level container. All other content, containers and
sl@0: // meta-data are nested inside. 
sl@0: // In an archive file applications can quickly search for the content objects they are interested in by using 
sl@0: // <code>ContentAccess::CContent::Search()</code>.
sl@0: // <hr>
sl@0: // Archive files containing several content objects cannot be referred to using just the URI of the file. The Content Access
sl@0: // Framework uses a concept of virtual paths to identify content objects within a file. The virtual path is a combination
sl@0: // of the file URI and a unique identifier supplied by the agent: 
sl@0: // A content file is only ever handled by the agent that recognises it. The unique identifier will never need to be 
sl@0: // decoded by anyone other that the agent that generated it, so the format is left for the agent to implement as it sees
sl@0: // fit. For instance an OMA DRM agent may put the Content ID (CID) in the \c UniqueId field.
sl@0: // The only constraint is that the \c UniqueId must be unique within the file. An application must be able to directly
sl@0: // reference a content object just using the <code>UniqueId</code>. 
sl@0: // <hr>
sl@0: // <b> Virtual Path pointer objects on the Stack </b>
sl@0: // The <code>ContentAccess::TVirtualPathPtr</code> is used to point to two descriptors holding the URI 
sl@0: // of a file and the <code>UniqueId</code> of a content object within the file. It can also be used to 
sl@0: // point to another <code>TVirtualPathPtr</code>. Since it is only a pointer, the original descriptors 
sl@0: // used to initalise the <code>TVirtualPathPtr</code> should not be destroyed or modified while the 
sl@0: // <code>TVirtualPathPtr</code> is still in use.
sl@0: // <b> Virtual Path objects on the heap </b>
sl@0: // The <code>ContentAccess::CVirtualPath</code> class stores the file URI and content object <code>UniqueId</code> in its own 
sl@0: // descriptors. There is a cast operator that allows the <code>CVirtualPath</code> to be used as 
sl@0: // if it were a <code>TVirtualPathPtr</code>.
sl@0: // <b> Examples </b>
sl@0: // // Open a CContent object to browse the objects inside a file
sl@0: // CContent *c = CContent::NewL(_L("C:\file.dcf"));
sl@0: // CleanupStack::PushL(c);
sl@0: // // Create an array to store the embedded objects
sl@0: // RStreamablePtrArray<CEmbeddedObject> myArray;
sl@0: // CleanupClosePushL(myArray);
sl@0: // // Get an array of the embedded objects within the current container in the file
sl@0: // c->GetEmbeddedObjectsL(myArray);
sl@0: // // If necessary we can get a "mangled" version of the URI that 
sl@0: // // references the particular object within the file
sl@0: // // ie. "C:\file.dcf\\OBJECT1"
sl@0: // TPtrC aURI = *myArray[0];
sl@0: // // Now we can use our TPtrC later to create a TVirtualPath object from a URI
sl@0: // TVirtualPathPtr aPtr = aURI;
sl@0: // // print the file URI  "C:\file.dcf"
sl@0: // printf(aPtr.URI());
sl@0: // // print the content object's UniqueId "OBJECT1"
sl@0: // printf(aPtr.UniqueId());
sl@0: // // Create a copy of aVirtualPath on the heap so we don't have any ownership problems
sl@0: // CVirtualPath *myVirtualpath = CVirtualPath::NewL(aPtr);
sl@0: // // Can now delete the CContent object without loosing our VirtualPath
sl@0: // CleanupStack::PopAndDestroy(2);	// c, myArray
sl@0: // <hr>
sl@0: // <b><code>KNullDesC16() -  ""</code></b>
sl@0: // 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
sl@0: // performed. The ability to open the file with no translation is required for example to attach the file to an outgoing message.
sl@0: // As with any other function in CAF access to the file is at the agents discretion.
sl@0: // <b><code>KDefaultContentObject() - "DEFAULT"</code></b>
sl@0: // Allows an application to refer to the default content object within a file. In the case of an unprotected file handled
sl@0: // by the \c F32Agent this will be the entire file, the same as if the <code>UniqueId ""</code> was used. Other agents, particularly those
sl@0: // with a single content object embedded within the file, use <code>"DEFAULT"</code> to refer to their only content object.
sl@0: // Even though the DEFAULT content object is supported, it is recommended that agents always use \c CContent to enumerate the 
sl@0: // objects within the file.
sl@0: // <hr>
sl@0: // 
sl@0: //
sl@0: 
sl@0: /**
sl@0:  @page FileOverview Files containing multiple content objects 
sl@0:  - @ref FileOverviewDescription
sl@0:  - @ref VirtualPaths
sl@0:  - @ref VirtualPathObjects
sl@0:  - @ref SpecialUniqueIds
sl@0:  @section FileOverviewDescription Structure of a file containing multiple content objects
sl@0:  related to a content object, see @ref ContentAttributes "Content Object Attributes".
sl@0:  @image html "multiple DRM file2.gif"
sl@0:  @section VirtualPaths Identifying a content object within a File
sl@0:  @li \c URI      - The location of the file
sl@0:  @li \c UniqueId - The content object inside the file.
sl@0:  @section VirtualPathObjects Objects used to identify a content object within a File
sl@0:  @code
sl@0:  @endcode
sl@0:  @section SpecialUniqueIds Special Cases for the UniqueId field
sl@0: */