1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/security/contentmgmt/contentaccessfwfordrm/engineering/dox/Attributes.dox Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,161 @@
1.4 +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// Each of these objects may have properties or attributes associated with it. This section
1.18 +// outlines how applications can retrieve these using the CAF API.
1.19 +// <hr>
1.20 +// Different agents may use different terms to describe the same concept. Generic attributes provide a
1.21 +// way for applications to query standardised information about a content object.
1.22 +// These standardised attributes are given by the enumeration <code>ContentAccess::TAttribute</code>. It is possible
1.23 +// for agents to extend this set of attributes, starting from <code>EAgentSpecificAttributeBase</code>.
1.24 +// The attribute functions are implemented in <code>ContentAccess::CContent</code>, <code>ContentAccess::CData</code> and
1.25 +// <code>ContentAccess::CManager</code>.
1.26 +// <b> Retrieving a Single Attribute </b>
1.27 +// The attributes of one content object in a file may not necessarily be the same as the
1.28 +// attributes of other content objects within the same file. Attributes relate to a single
1.29 +// content object within a file.
1.30 +// It is possible that the attribute may not make sense for a particular content object. In that
1.31 +// case the agent will return an error <code>KErrCANotSupported</code>. If an attempt is made to
1.32 +// retrieve the attributes of a content object that does not exist the agent will return <code>KErrNotFound</code>.
1.33 +// The following code fragment illustrates how to retrieve an attribute for a particular
1.34 +// object within a content file.
1.35 +// CContent* content = CContent::NewL(uri);
1.36 +// // check if DRM rights are pending for the object specified by uniqueId
1.37 +// TInt attributeValue;
1.38 +// TInt err = content->GetAttribute(ERightsPending, attributeValue, uniqueId);
1.39 +// if(err == KErrNone)
1.40 +// // Check the value of the attribute
1.41 +// if(attributeValue == ETrue)
1.42 +// // Rights are pending, display waiting for rights countdown
1.43 +// else if(attributeValue == EFalse)
1.44 +// // Rights are not pending
1.45 +// else if(err == KErrCANotSupported)
1.46 +// // This attribute does not apply to this content object
1.47 +// else if(err == KErrNotFound)
1.48 +// // Cannot find the object specified by the given uniqueId
1.49 +// else if (err != KErrPermissionDenied)
1.50 +// // Unknown error
1.51 +// User::Leave(err);
1.52 +// <b> Retrieving Several Attributes </b>
1.53 +// For some agent implementations it may be more efficient to retrieve all the attributes for a content
1.54 +// object in one function call. The <code>ContentAccess::RAttributeSet</code> object is used here to provide a way to
1.55 +// request and store several attributes.
1.56 +// Querying two attributes using the CManager API would look like the following:
1.57 +// // Agent manager
1.58 +// CManager *manager = CManager::NewLC();
1.59 +// // Prepare the attributes to query using the CAttributeSet object
1.60 +// RAttributeSet attributeSet;
1.61 +// CleanupClosePushL(attributeSet);
1.62 +// attributeSet.AddL(EProtected);
1.63 +// attributeSet.AddL(ECanView);
1.64 +// // Retrieve the attribute values from the agent
1.65 +// User::LeaveIfError(manager->GetAttributeSet(attributeSet, virtualPath));
1.66 +// // Check if the content object is protected
1.67 +// TInt attributeValue;
1.68 +// TInt err = attributeSet.GetValue(EProtected, attributeValue);
1.69 +// if(err == KErrNone && attributeValue)
1.70 +// // content object is DRM protected
1.71 +// // Check if the content object can be display on screen
1.72 +// TInt err = attributeSet.GetValue(ECanView, attributeValue);
1.73 +// if(err == KErrNone && attributeValue)
1.74 +// // content object has rights that allow it to be displayed on screen
1.75 +// // Finished
1.76 +// CleanupStack::PopAndDestroy(2); // manager, attributeSet
1.77 +// <hr>
1.78 +// String attributes are similar to the attributes described above except the value associated
1.79 +// with the attribute is a string. A good example of where a string attribute is required is the
1.80 +// MIME type of a content object within a file.
1.81 +// The string attributes are standardised by the <code>ContentAccess::TStringAttribute</code> enumeration. This
1.82 +// allows applications to request information such as the MIME type in a generic way for all agents.
1.83 +// Agents can extend this mechanism to provide agent specific attributes starting at
1.84 +// <code>EAgentSpecificStringAttributeBase</code>.
1.85 +// The following example finds the author of a content object.
1.86 +// CContent* content = CContent::NewL(uri);
1.87 +// // define a buffer to store the attribute value string
1.88 +// TBuf <100> buf;
1.89 +// // retrieve the attribute
1.90 +// err = content->GetAttribute(EAuthor, authorBuffer, uniqueId);
1.91 +// // Display the authors name on screen
1.92 +// if (err == KErrNone)
1.93 +// DisplayAuthor(buf);
1.94 +// If the Agent does not support this attribute, it will return <code>KErrCANotSupported</code>.
1.95 +// <b> Retrieving Several String Attributes </b>
1.96 +// For some agent implementations it may be more efficient to retrieve several string attributes for a content
1.97 +// object in one function call. The <code>ContentAccess::RStringAttributeSet</code> object is used here to provide a way to
1.98 +// request and store several attributes.
1.99 +// Querying three attributes using the CManager API would look like the following:
1.100 +// CManager *manager = CManager::NewLC();
1.101 +// // Prepare the attributes to query using the CAttributeSet object
1.102 +// RStringAttributeSet stringAttributeSet;
1.103 +// CleanupClosePushL(stringAttributeSet);
1.104 +// stringAttributeSet.AddL(ETitle);
1.105 +// stringAttributeSet.AddL(EAuthor);
1.106 +// stringAttributeSet.AddL(EDescription);
1.107 +// // Retrieve the attribute values from the agent
1.108 +// User::LeaveIfError(manager->GetStringAttributeSet(stringAttributeSet, virtualPath));
1.109 +// // Display the values
1.110 +// TBuf <256> value;
1.111 +// TInt err = stringAttributeSet.GetValue(ETitle, value);
1.112 +// if(err == KErrNone)
1.113 +// Printf("Title : %s", value);
1.114 +// err = stringAttributeSet.GetValue(EAuthor, value);
1.115 +// if(err == KErrNone)
1.116 +// Printf("Author : %s", value);
1.117 +// err = stringAttributeSet.GetValue(EDescription, value);
1.118 +// if(err == KErrNone)
1.119 +// Printf("Description : %s", value);
1.120 +// // Finished
1.121 +// CleanupStack::PopAndDestroy(2); // manager, stringAttributeSet
1.122 +// <hr>
1.123 +// Some agents may expose meta data so they can be read using a \c CData object. The format
1.124 +// of these meta-data objects is not specified by the Content Access Framework but could
1.125 +// be useful for applications familiar with the agent to read meta data this way.
1.126 +// \c CData objects for agent specific meta-data can be opened in the same way content objects
1.127 +// are opened using the <code>ContentAccess::CContent::OpenContentL()</code> function.
1.128 +// CContent* content = CContent::NewLC(uri);
1.129 +// // Create an array to store the embedded objects
1.130 +// RStreamablePtrArray<CEmbeddedObject> myArray;
1.131 +// CleanupClosePushL(myArray);
1.132 +// // Get the embedded "Agent Specific" objects in the current container
1.133 +// content->GetEmbeddedObjectsL(myArray, EAgentSpecificObject);
1.134 +// // Get the unique Id of the first meta-data object
1.135 +// TPtrC aUniqueId = myArray[0]->UniqueId();
1.136 +// // create a CData object to read the meta data
1.137 +// CData *myMetaData = content->OpenContentLC(EPeek, aUniqueId);
1.138 +// // Do something with the data
1.139 +// // Finished
1.140 +// CleanupStack::PopAndDestroy(3); // content, myArray, myMetaData
1.141 +// <hr>
1.142 +//
1.143 +//
1.144 +
1.145 +/**
1.146 + @page ContentAttributes Content Object Attributes
1.147 + As shown in the @ref CContentAPI "Consumer API", a file may consist of many content and container objects.
1.148 + - @ref CAFAttributes
1.149 + - @ref CAFStringAttributes
1.150 + - @ref CAFAgentSpecificMetaData
1.151 + @section CAFAttributes Generic Attributes
1.152 + @code
1.153 + @endcode
1.154 + @code
1.155 + @endcode
1.156 + @section CAFStringAttributes Generic String attributes
1.157 + @code
1.158 + @endcode
1.159 + @code
1.160 + @endcode
1.161 + @section CAFAgentSpecificMetaData Agent specific meta-data
1.162 + @code
1.163 + @endcode
1.164 +*/