<?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-&gt;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-&gt;GetAttributeSet(attributeSet,virtualPath);

// Check if the content object is protected 
TInt attributeValue;
TInt err = attributeSet.GetValue(EProtected, attributeValue); 
if(err == KErrNone &amp;&amp; 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 &amp;&amp; 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-&gt;GetStringAttributeSet(stringAttributeSet,virtualPath));

// Display the values 
TBuf &lt;256&gt; 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>
</conbody></concept>