sl@0: // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: // All rights reserved.
sl@0: // This component and the accompanying materials are made available
sl@0: // under the terms of the License "Eclipse Public License v1.0"
sl@0: // which accompanies this distribution, and is available
sl@0: // at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: //
sl@0: // Initial Contributors:
sl@0: // Nokia Corporation - initial contribution.
sl@0: //
sl@0: // Contributors:
sl@0: //
sl@0: // Description:
sl@0: // Each of these objects may have properties or attributes associated with it. This section
sl@0: // outlines how applications can retrieve these using the CAF API.
sl@0: // <hr>
sl@0: // Different agents may use different terms to describe the same concept. Generic attributes provide a 
sl@0: // way for applications to query standardised information about a content object. 
sl@0: // These standardised attributes are given by the enumeration <code>ContentAccess::TAttribute</code>. It is possible 
sl@0: // for agents to extend this set of attributes, starting from <code>EAgentSpecificAttributeBase</code>. 
sl@0: // The attribute functions are implemented in <code>ContentAccess::CContent</code>, <code>ContentAccess::CData</code> and 
sl@0: // <code>ContentAccess::CManager</code>.
sl@0: // <b> Retrieving a Single Attribute </b>
sl@0: // The attributes of one content object in a file may not necessarily be the same as the
sl@0: // attributes of other content objects within the same file. Attributes relate to a single
sl@0: // content object within a file. 
sl@0: // It is possible that the attribute may not make sense for a particular content object. In that 
sl@0: // case the agent will return an error <code>KErrCANotSupported</code>. If an attempt is made to 
sl@0: // retrieve the attributes of a content object that does not exist the agent will return <code>KErrNotFound</code>.
sl@0: // The following code fragment illustrates how to retrieve an attribute for a particular
sl@0: // object within a content file.
sl@0: // CContent* content = CContent::NewL(uri);
sl@0: // // check if DRM rights are pending for the object specified by uniqueId
sl@0: // TInt attributeValue;
sl@0: // TInt err = content->GetAttribute(ERightsPending, attributeValue, uniqueId);
sl@0: // if(err == KErrNone)
sl@0: // // Check the value of the attribute
sl@0: // if(attributeValue == ETrue)
sl@0: // // Rights are pending, display waiting for rights countdown
sl@0: // else if(attributeValue == EFalse)
sl@0: // // Rights are not pending
sl@0: // else if(err == KErrCANotSupported)
sl@0: // // This attribute does not apply to this content object
sl@0: // else if(err == KErrNotFound)
sl@0: // // Cannot find the object specified by the given uniqueId
sl@0: // else if (err != KErrPermissionDenied)
sl@0: // // Unknown error
sl@0: // User::Leave(err);
sl@0: // <b> Retrieving Several Attributes </b>
sl@0: // For some agent implementations it may be more efficient to retrieve all the attributes for a content
sl@0: // object in one function call. The <code>ContentAccess::RAttributeSet</code> object is used here to provide a way to
sl@0: // request and store several attributes.
sl@0: // Querying two attributes using the CManager API would look like the following:
sl@0: // // Agent manager
sl@0: // CManager *manager = CManager::NewLC();
sl@0: // // Prepare the attributes to query using the CAttributeSet object
sl@0: // RAttributeSet attributeSet;
sl@0: // CleanupClosePushL(attributeSet);
sl@0: // attributeSet.AddL(EProtected);
sl@0: // attributeSet.AddL(ECanView);
sl@0: // // Retrieve the attribute values from the agent
sl@0: // User::LeaveIfError(manager->GetAttributeSet(attributeSet, virtualPath));
sl@0: // // Check if the content object is protected
sl@0: // TInt attributeValue;
sl@0: // TInt err = attributeSet.GetValue(EProtected, attributeValue);
sl@0: // if(err == KErrNone && attributeValue)
sl@0: // // content object is DRM protected
sl@0: // // Check if the content object can be display on screen
sl@0: // TInt err = attributeSet.GetValue(ECanView, attributeValue);
sl@0: // if(err == KErrNone && attributeValue)
sl@0: // // content object has rights that allow it to be displayed on screen
sl@0: // // Finished	
sl@0: // CleanupStack::PopAndDestroy(2);		// manager, attributeSet
sl@0: // <hr>
sl@0: // String attributes are similar to the attributes described above except the value associated
sl@0: // with the attribute is a string. A good example of where a string attribute is required is the
sl@0: // MIME type of a content object within a file. 
sl@0: // The string attributes are standardised by the <code>ContentAccess::TStringAttribute</code> enumeration. This
sl@0: // allows applications to request information such as the MIME type in a generic way for all agents.
sl@0: // Agents can extend this mechanism to provide agent specific attributes starting at 
sl@0: // <code>EAgentSpecificStringAttributeBase</code>.
sl@0: // The following example finds the author of a content object.
sl@0: // CContent* content = CContent::NewL(uri);
sl@0: // // define a buffer to store the attribute value string
sl@0: // TBuf <100> buf;
sl@0: // // retrieve the attribute
sl@0: // err = content->GetAttribute(EAuthor, authorBuffer, uniqueId);
sl@0: // // Display the authors name on screen
sl@0: // if (err == KErrNone)
sl@0: // DisplayAuthor(buf);
sl@0: // If the Agent does not support this attribute, it will return <code>KErrCANotSupported</code>.
sl@0: // <b> Retrieving Several String Attributes </b>
sl@0: // For some agent implementations it may be more efficient to retrieve several string attributes for a content
sl@0: // object in one function call. The <code>ContentAccess::RStringAttributeSet</code> object is used here to provide a way to
sl@0: // request and store several attributes.
sl@0: // Querying three attributes using the CManager API would look like the following:
sl@0: // CManager *manager = CManager::NewLC();
sl@0: // // Prepare the attributes to query using the CAttributeSet object
sl@0: // RStringAttributeSet stringAttributeSet;
sl@0: // CleanupClosePushL(stringAttributeSet);
sl@0: // stringAttributeSet.AddL(ETitle);
sl@0: // stringAttributeSet.AddL(EAuthor);
sl@0: // stringAttributeSet.AddL(EDescription);
sl@0: // // Retrieve the attribute values from the agent
sl@0: // User::LeaveIfError(manager->GetStringAttributeSet(stringAttributeSet, virtualPath));
sl@0: // // Display the values
sl@0: // TBuf <256> value;
sl@0: // TInt err = stringAttributeSet.GetValue(ETitle, value);
sl@0: // if(err == KErrNone)
sl@0: // Printf("Title       : %s", value);
sl@0: // err = stringAttributeSet.GetValue(EAuthor, value);
sl@0: // if(err == KErrNone)
sl@0: // Printf("Author      : %s", value);
sl@0: // err = stringAttributeSet.GetValue(EDescription, value);
sl@0: // if(err == KErrNone)
sl@0: // Printf("Description : %s", value);
sl@0: // // Finished
sl@0: // CleanupStack::PopAndDestroy(2);		// manager, stringAttributeSet
sl@0: // <hr>
sl@0: // Some agents may expose meta data so they can be read using a \c CData object. The format 
sl@0: // of these meta-data objects is not specified by the Content Access Framework but could 
sl@0: // be useful for applications familiar with the agent to read meta data this way.
sl@0: // \c CData objects for agent specific meta-data can be opened in the same way content objects
sl@0: // are opened using the <code>ContentAccess::CContent::OpenContentL()</code> function.
sl@0: // CContent* content = CContent::NewLC(uri);
sl@0: // // Create an array to store the embedded objects 
sl@0: // RStreamablePtrArray<CEmbeddedObject> myArray;
sl@0: // CleanupClosePushL(myArray);
sl@0: // // Get the embedded "Agent Specific" objects in the current container
sl@0: // content->GetEmbeddedObjectsL(myArray, EAgentSpecificObject);
sl@0: // // Get the unique Id of the first meta-data object
sl@0: // TPtrC aUniqueId = myArray[0]->UniqueId();
sl@0: // // create a CData object to read the meta data
sl@0: // CData *myMetaData = content->OpenContentLC(EPeek, aUniqueId);
sl@0: // // Do something with the data
sl@0: // // Finished
sl@0: // CleanupStack::PopAndDestroy(3);		// content, myArray, myMetaData
sl@0: // <hr>
sl@0: // 
sl@0: //
sl@0: 
sl@0: /**
sl@0:  @page ContentAttributes Content Object Attributes
sl@0:  As shown in the @ref CContentAPI "Consumer API", a file may consist of many content and container objects.
sl@0:  - @ref CAFAttributes
sl@0:  - @ref CAFStringAttributes
sl@0:  - @ref CAFAgentSpecificMetaData 
sl@0:  @section CAFAttributes Generic Attributes
sl@0:  @code
sl@0:  @endcode
sl@0:  @code
sl@0:  @endcode
sl@0:  @section CAFStringAttributes Generic String attributes
sl@0:  @code
sl@0:  @endcode
sl@0:  @code
sl@0:  @endcode
sl@0:  @section CAFAgentSpecificMetaData Agent specific meta-data
sl@0:  @code
sl@0:  @endcode
sl@0: */