Files +Containing Multiple Content Objects

Content Access Framework provides a generic mechanism for exploring files +that contain multiple content objects. These files are often referred to as +archive files. This can be .ZIP compression archive or +a DRM protected archive, such as an OMA .DCF file. An +application can explore the content objects inside a file using the ContentAccess::CContent class.

Structure of a file containing multiple content objects

An +archive file can have content objects and meta-data or information associated +with the content. This meta-data can include information, such as the MIME +type of the content, the encryption algorithm, the compressed size of the +content. This information can be retrieved from the attributes related to +a content object, see Content +Object Attributes.

The content and meta-data may also be arranged +in a hierachy with container objects grouping content objects together. A +typical archive can have a complex structure as the example shown below:

+ +

In this scenario, the file itself can be considered as the top level +container. All other content, containers and meta-data are nested inside. +In an archive file, applications can quickly search for the content objects +they are interested in by using ContentAccess::CContent::Search(), +see Consumer API Tutorial.

Identifying +a content object within a file

Archive files containing several +content objects cannot be referred to using just the URI of the file. The +Content Access Framework uses a concept of virtual paths to identify content +objects within a file. The virtual path is a combination of the file URI and +a unique identifier supplied by the agent:

URI: +the location of the file.
UniqueId: +the content object inside the file.

A content file is only handled by the agent that recognises it. The +unique identifier is not required to be decoded by anyone other than the agent +that generated it, so the format is left for the agent to implement as it +sees fit. For instance, an OMA DRM agent may put the Content ID (CID) in the UniqueId field.

The +only constraint is that the UniqueId must be unique within +the file. An application must be able to directly reference a content object +just using the UniqueId.

Objects used +to identify a content object within a file

Virtual path pointer +objects on the stack

The ContentAccess::TVirtualPathPtr is +used to point to two descriptors holding the URI of a file and the UniqueId of +a content object within the file. It can also be used to point to another TVirtualPathPtr. +Since it is only a pointer, the original descriptors used to initalise the TVirtualPathPtr must +not be destroyed or modified while the TVirtualPathPtr is +still in use.

Virtual path objects on the heap

The ContentAccess::CVirtualPath class +stores the file URI and content object UniqueId in its own +descriptors. There is a cast operator that allows the CVirtualPath to +be used as if it were a TVirtualPathPtr .

Examples

// Open a CContent object to browse the objects inside a file +CContent *c = CContent::NewL(_L("C:\file.dcf")); +CleanupStack::PushL(c); + +// Create an array to store the embedded objects +RStreamablePtrArray<CEmbeddedObject> myArray; + +// Get an array of the embedded objects within the current container in the file +c->GetEmbeddedObjects(myArray); + +// If necessary we can get a "mangled" version of the URI that +// references the particular object within the file +// i.e. "C:\file.dcf\\OBJECT1" + +CData* data = iContent->OpenContentL(EPlay,myArray[0]->UniqueId()); + +TFileName uri; +data->GetStringAttribute(EPreviewURI,uri); +. +. +. +// Now we can use our TPtrC later to create a TVirtualPath object from a URI +TVirtualPathPtr aPtr = aURI; + +// print the file URI "C:\file.dcf" +printf(aPtr.URI()); + +// print the content object's UniqueId "OBJECT1" +printf(aPtr.UniqueId()); + +// Create a copy of the virtual path on the heap so we don't have any ownership problems +CVirtualPath *myVirtualpath = CVirtualPath::NewL(aPtr) + +// Can now delete the CContent object without losing our VirtualPath +CleanupStack::PopAndDestroy(c);

Special cases for the UniqueId field

KNullDesC16() +- ""

A zero length UniqueId is used to refer +to the entire file. If a file is opened this way, no translation of the contents +is performed. The ability to open the file with no translation is required +for example to attach the file to an outgoing message. As with any other function +in CAF, access to the file is at the agent's discretion.

KDefaultContentObject() +- "DEFAULT"

Allows an application to refer to the default content +object within a file. In the case of an unprotected file handled by the F32Agent, +it is the entire file, the same as if the UniqueId "" was +used. Other agents, particularly those with a single content object embedded +within the file, use "DEFAULT" to refer to their only content +object.

Even though the DEFAULT content object is +supported, it is recommended that agents always use CContent to +enumerate the objects within the file.