Content object attributes

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