--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-B6912FE7-4C2A-5FC7-BDA8-702CA2C0214A.dita	Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,133 @@
+<?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>
\ No newline at end of file