Content +object attributes

A file may consist of many content and container objects. Each of these +objects may have properties or attributes associated with it. Applications +can retrieve these using the CAF APIs.

Generic attributes

Different agents may use different +terms to describe the same concept. Generic attributes provide a way for applications +to query standardised information about a content object.

These standardised +attributes are given by the enumeration ContentAccess::TAttribute. +It is possible for agents to extend this set of attributes, starting from EAgentSpecificAttributeBase.

The +attribute functions are implemented in ContentAccess::CContent, ContentAccess::CData and ContentAccess::CManager.

Retrieving a single attribute

The attributes of +one content object in a file may not necessarily be the same as the attributes +of other content objects within the same file. Attributes relate to a single +content object within a file.

It is possible that the attribute may +not make sense for a particular content object. In that case, the agent will +return a KErrCANotSupported error. If an attempt is made +to retrieve the attributes of a content object that does not exist, the agent +will return KErrNotFound.

The following code fragment +illustrates how to retrieve an attribute for a particular object within a +content file.

// check if DRM rights are pending for the object specified by uniqueId + +TInt attributeValue; +TInt err = content->GetAttribute(ERightsPending, attributeValue, uniqueId); + +if(err == KErrNone) + { + // Check the value of the attribute + if(attributeValue == ETrue) + { + // Rights are pending, display waiting for rights countdown + } + + else if(attributeValue == EFalse) + { + // Rights are not pending + } + } + +else if(err == KErrCANotSupported) + { + // This attribute does not apply to this content object + } + +else if(err == KErrNotFound) + { + // Cannot find the object specified by the given uniqueId + }

Retrieving several attributes

For some +agent implementations it may be more efficient to retrieve all the attributes +for a content object in one function call. The ContentAccess::RAttributeSet object +is used here to provide a way to request and store several attributes.

Querying +two attributes using the CManager API would look like the +following:

// Prepare the attributes to query using the CAttributeSet object + +RAttributeSet attributeSet; +CleanupClosePushL(attributeSet); + +attributeSet.AddL(EProtected); +attributeSet.AddL(ECanView); + +CManager *manager = new CManager(); + +// Retrieve the attribute values from the agent +User::LeaveIfError(manager->GetAttributeSet(attributeSet,virtualPath); + +// Check if the content object is protected +TInt attributeValue; +TInt err = attributeSet.GetValue(EProtected, attributeValue); +if(err == KErrNone && attributeValue) + { + // content object is DRM protected + } + +// Check if the content object can be display on screen +TInt err = attributeSet.GetValue(ECanView, attributeValue); +if(err == KErrNone && attributeValue) + { + // content object has rights that allow it to be displayed on screen + }

Generic string attributes

String attributes are +similar to the attributes described above except the value associated with +the attribute is a string. A good example of where a string attribute is required +is the MIME type of a content object within a file.

The string attributes +are standardised by the ContentAccess::TStringAttribute enumeration. +This allows applications to request information such as the MIME type in a +generic way for all agents.

Agents can extend this mechanism to provide +agent specific attributes starting at EAgentSpecificStringAttributeBase. +If the Agent does not support this attribute, it returns KErrCANotSupported.

Retrieving +several string attributes

For some agent implementations, it +may be more efficient to retrieve several string attributes for a content +object in one function call. The ContentAccess::RStringAttributeSet object +is used here to provide a way to request and store several attributes.

The +following example query three attributes using the CManager API:

// Prepare the attributes to query using the CAttributeSet object +RStringAttributeSet stringAttributeSet; +CleanupClosePushL(stringAttributeSet); + +stringAttributeSet.AddL(ETitle); +stringAttributeSet.AddL(EAuthor); +stringAttributeSet.AddL(EDescription); + +CManager *manager = new CManager(); + +// Retrieve the attribute values from the agent +User::LeaveIfError(manager->GetStringAttributeSet(stringAttributeSet,virtualPath)); + +// Display the values +TBuf <256> value; +TInt err = stringAttributeSet.GetValue(ETitle, value); +if(err == KErrNone) + { + Printf("Title : %s", value); + } +err = stringAttributeSet.GetValue(EAuthor, value); +if(err == KErrNone) + { + Printf("Author : %s", value); + } +err = stringAttributeSet.GetValue(EDescription, value); +if(err == KErrNone) + { + Printf("Description : %s", value); + }