<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-B6912FE7-4C2A-5FC7-BDA8-702CA2C0214A" xml:lang="en"><title>Content

object attributes</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>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. </p>

<section><title>Generic attributes</title> <p>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. </p> <p>These standardised

attributes are given by the enumeration <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-BC47B375-3FC2-3F1E-93A8-9CD4314439A0"><apiname>ContentAccess::TAttribute</apiname></xref>.

It is possible for agents to extend this set of attributes, starting from <xref href="GUID-D72F3CCA-05E7-323B-9F35-18D1338F71D0.dita"><apiname>EAgentSpecificAttributeBase</apiname></xref>. </p> <p>The

attribute functions are implemented in <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-FC40011B-32D3-328B-BB59-35BEF46A215A"><apiname>ContentAccess::CContent</apiname></xref>, <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-B54C8391-FE69-324C-AC0A-1E88C2555F00"><apiname>ContentAccess::CData</apiname></xref> and <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-671191B1-B249-3DD3-A5E8-6F1A41A371C8"><apiname>ContentAccess::CManager</apiname></xref>. </p> <p><b>Retrieving a single attribute </b> </p> <p>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. </p> <p>It is possible that the attribute may

not make sense for a particular content object. In that case, the agent will

return a <codeph>KErrCANotSupported</codeph> error. If an attempt is made

to retrieve the attributes of a content object that does not exist, the agent

will return <codeph>KErrNotFound</codeph>. </p> <p>The following code fragment

illustrates how to retrieve an attribute for a particular object within a

content file. </p> <codeblock id="GUID-E773CC84-3C78-5B81-A39F-8C2780554BA4" xml:space="preserve">// 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 

    }</codeblock> <p><b>Retrieving several attributes </b> </p> <p>For some

agent implementations it may be more efficient to retrieve all the attributes

for a content object in one function call. The <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-19C830CE-9E8C-381B-9D76-74B110C3A7D9"><apiname>ContentAccess::RAttributeSet</apiname></xref> object

is used here to provide a way to request and store several attributes. </p> <p>Querying

two attributes using the <xref href="GUID-7F3D9E35-A8FC-35A6-8036-23396BAADFDC.dita"><apiname>CManager</apiname></xref> API would look like the

following: </p> <codeblock id="GUID-6FE754AF-471E-5A79-847F-D994D1C7981D" xml:space="preserve">// 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 

    }</codeblock> </section>

<section><title>Generic string attributes</title> <p>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. </p> <p>The string attributes

are standardised by the <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-BC242813-E0F0-3DFE-AF97-6BE808D570DE"><apiname>ContentAccess::TStringAttribute</apiname></xref> enumeration.

This allows applications to request information such as the MIME type in a

generic way for all agents. </p> <p>Agents can extend this mechanism to provide

agent specific attributes starting at <xref href="GUID-7BF5E37F-2F46-33EB-B0A8-266532570BA2.dita"><apiname>EAgentSpecificStringAttributeBase</apiname></xref>.

If the Agent does not support this attribute, it returns <codeph>KErrCANotSupported</codeph>. </p> <p><b>Retrieving

several string attributes </b> </p> <p>For some agent implementations, it

may be more efficient to retrieve several string attributes for a content

object in one function call. The <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-E441CC4B-5BB0-36C4-A4B3-40A71FE2B156"><apiname>ContentAccess::RStringAttributeSet</apiname></xref> object

is used here to provide a way to request and store several attributes. </p> <p>The

following example query three attributes using the <xref href="GUID-7F3D9E35-A8FC-35A6-8036-23396BAADFDC.dita"><apiname>CManager</apiname></xref> API: </p> <codeblock id="GUID-05C8EDBD-4CCA-5214-8466-F060B4F6425E" xml:space="preserve">// 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); 

    }</codeblock> </section>