Files containing multiple content objects

An application can explore the content objects inside a file using the ContentAccess::CContent class.

The 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 could be anything from a .ZIP compression archive to a DRM protected archive such as an OMA .DCF file.

Inside an archive file, and in addition to the content objects, there will be meta-data or information associated with the content. This meta-data could 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 could have a complex structure like the example shown below:

In this situation, 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().

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 ever handled by the agent that recognises it. The unique identifier will never need 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.

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 should 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);

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 will be 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, this will be 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.