Consumer API (Browsing and reading from content files)

An example content file is given below. It has a number of content objects and a number of containers with other containers and content objects inside. It is likely that each container will have information or meta-data related to the collection of objects it holds.

The ContentAccess::CContent object encapsulates a single file. It allows an application to look at the structure of the objects within the file and the attributes of those objects.

There are two ways to create a CContent object. The application can specify the URI of the content or it can supply an open file handle.

// Create a CContent with a URI 
CContent *content = CContent::NewL(uri); 

// Create a CContent with an existing file handle
CContent *content = CContent::NewL(aFs, aFile);

Upon creation, CContent selects the agent that will handle the file.

ContentAccess::CContent acts like a cursor, only able to list the contents of one container object at any one time. When CContent is first opened, it views the top level container within the file. The top level container is actually the file itself. This top level container concept applies to all files, regardless of how many content or container objects are inside.

Even a content file such as a jpeg image is a container, it's just that the file only has the "DEFAULT" object embedded inside.

So, when the example file shown earlier is opened, the following objects can be seen by the CContent:

In this top level container, there is only one embedded content object visible (the .jpg file) and two embedded container objects.

// Create an array to store the results of CContent::GetEmbeddedObjectsL() 
RStreamablePtrArray<CEmbeddedObject> myArray; 
CleanupClosePushL(myArray); 
    
// Get the embedded content objects in the current container 
content->GetEmbeddedObjectsL(myArray, EContentObject); 

i = myArray.Count(); // One content object 

// clear the contents of the array 
myArray.ResetAndDestroy(); 
    
// Get the number of container objects in the current container
content->GetEmbeddedObjectsL(myArray, EContainerObject); 

i = myArray.Count(); // Two container objects 
                    
// clear the contents of the array 
myArray->ResetAndDestroy();

To investigate the objects inside a container, CContent must first open the container. This changes CContent's focus from the current container to the container specified in the ContentAccess::CContent::OpenContainer() function.

Opening container 1 from the top level of the file

// Get the container objects in the top level of the file 
content->GetEmbeddedObjects(myArray, EContainerObject); 

// Find the Unique Id of the first container 
TPtrC UniqueId = myArray[0]->UniqueId() 

// Open the first container 
content->OpenContainer(UniqueId);

Now CContent can see the contents of Container 1:

At this point, listing the objects that CContent can see gives six MP3 files and one container object.

// Get the embedded content objects in the current container 
content->GetEmbeddedObjectsL(myArray, EContentObject); 
                 
i = myArray.Count(); // Six content objects
myArray.ResetAndDestroy(); 
                    
// Get the number of container objects in the current container 
content->GetEmbeddedObjectsL(myArray, EContainerObject);
                          
i = myArray.Count(); // One container object 
myArray.ResetAndDestroy();

Opening Container 1.1 from Container 1

The same process can be followed again to see the contents of Container 1.1

// Get the array of container objects in the current container
content->GetEmbeddedObjects(myArray, EContainerObject); 

// Find the Unique Id of the first container within Container 1
TPtrC UniqueId = myArray[0]->UniqueId() 
                                                                                                    
// Open Container 1.1 
content->OpenContainer(UniqueId); 
myArray.ResetAndDestroy();

// Can now see two content objects (the MOV file and the TXT file) 
content->GetEmbeddedObjectsL(myArray, EContentObject); 
i = myArray.Count(); 
myArray.ResetAndDestroy();

// Zero container objects 
content->GetEmbeddedObjectsL(myArray,EContentObject); 
i = myArray.Count(); 
myArray.ResetAndDestroy();

To look once more at the contents of the container that encloses the current container, the ContentAccess::CContent::CloseContainer() function should be used.

Continuing our example, if we close the Container 1.1 we are left viewing the Container 1 again.

//Close Container 1.1 
content->CloseContainer(); 

// Get the embedded content objects in the current container 
content->GetEmbeddedObjectsL(myArray, EContentObject);
i = myArray.Count(); // Six content objects 
myArray.ResetAndDestroy(); 

// Get the number of container objects in the current container 
content->GetEmbeddedObjectsL(myArray, EContainerObject); 
i = myArray.Count(); // One container object 
myArray.ResetAndDestroy();

If an application wants to find all the content with a particular MIME type within a file, it should use ContentAccess::CContent::Search(). This function will produce a list of all content objects with the specified MIME type that are stored under the current container.

// Create an array for storing the result of the search 
RStreamablePtrArray<CEmbeddedObject> myArray; 

// Find how many MP3 files are in Container 1 
TInt numMp3 = content->Search(myArray, _L("mpeg/audio"), EFalse);

The functions described earlier can be used to locate a particular content object within a file. ContentAccess::CContent::OpenContentL() can be used to read the content object. The UniqueId parameter can be used to identify a particular object within the file.

The call to ContentAccess::CContent::OpenContentL() will leave if the intent is not permitted. This could occur if the file is DRM protected but no rights are present.

If the file is DRM protected and the call to OpenContentL() succeeds, the rights are not consumed at this point. CAF just checks that it is possible to use the content.

// Open the content object specified by uniqueId with the EPlay intent 
CData* data = content->OpenContentL(EPlay, uniqueId);

If the application already knows the URI and unique ID of the content object it wants to read from, it can create a CData object directly.

CData* data = CData::NewL(TVirtualPathPtr(uri, uniqueId), EPlay, EContentShareReadOnly);

Once the CData object has been constructed, it allows the content object to be used as if it were a standalone unprotected file. The client must call ContentAccess::CData::ExecuteIntent() when the rights should be consumed. If the file is not DRM protected, the call will be ignored by the agent handling the file.

TBuf8 <256> buf; 
data->ExecuteIntent(EPlay); 
data->Seek(ESEEK_START,SomePosition); 
data->Read(buf);

There are several overloaded versions of the ContentAccess::CData::Read() function. Only one is illustrated above for example purposes.

The CContent interface supports notification requests for content objects within files. The events for which an application can request notification are given by the enumeration ContentAccess::TEventMask.

The following example requests and cancels notification for rights becoming available:

// Request notification when rights become available for a particular content object
content->NotifyStatusChange(ERightsAvailable, status, uniqueId);

// Cancel notification request
content->CancelNotifyStatusChange(status, uniqueId);

There are two functions available that give the application some control over the rights:

Request rights

ContentAccess::CContent::RequestRights() allows the application to ask the agent to undertake whatever steps are necessary to obtain rights for the given content object. Some agents may not support this mechanism, in which case they will return KErrCANotSupported.

The request rights call includes a TRequestStatus parameter, which allows the application to be notified of the outcome of the rights request.

content->RequestRights(status, uniqueId);

Display info

ContentAccess::CContent::DisplayInfoL() allows the application to ask the agent to display the file and/or rights information for the given content object. The call returns when the display is dismissed.

Some agents may not support this mechanism, in which case they will return KErrCANotSupported.

content->DisplayInfoL(EFileProperties, uniqueId);