diff -r 48780e181b38 -r 578be2adaf3e Symbian3/PDK/Source/GUID-B6912FE7-4C2A-5FC7-BDA8-702CA2C0214A.dita --- a/Symbian3/PDK/Source/GUID-B6912FE7-4C2A-5FC7-BDA8-702CA2C0214A.dita Tue Jul 20 12:00:49 2010 +0100 +++ b/Symbian3/PDK/Source/GUID-B6912FE7-4C2A-5FC7-BDA8-702CA2C0214A.dita Fri Aug 13 16:47:46 2010 +0100 @@ -1,133 +1,133 @@ - - - - - -Content -object attributes -

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.

-
Generic attributes

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.

These standardised -attributes are given by the enumeration ContentAccess::TAttribute. -It is possible for agents to extend this set of attributes, starting from EAgentSpecificAttributeBase.

The -attribute functions are implemented in ContentAccess::CContent, ContentAccess::CData and ContentAccess::CManager.

Retrieving a single attribute

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.

It is possible that the attribute may -not make sense for a particular content object. In that case, the agent will -return a KErrCANotSupported error. If an attempt is made -to retrieve the attributes of a content object that does not exist, the agent -will return KErrNotFound.

The following code fragment -illustrates how to retrieve an attribute for a particular object within a -content file.

// 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 - }

Retrieving several attributes

For some -agent implementations it may be more efficient to retrieve all the attributes -for a content object in one function call. The ContentAccess::RAttributeSet object -is used here to provide a way to request and store several attributes.

Querying -two attributes using the CManager API would look like the -following:

// 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 - }
-
Generic string attributes

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.

The string attributes -are standardised by the ContentAccess::TStringAttribute enumeration. -This allows applications to request information such as the MIME type in a -generic way for all agents.

Agents can extend this mechanism to provide -agent specific attributes starting at EAgentSpecificStringAttributeBase. -If the Agent does not support this attribute, it returns KErrCANotSupported.

Retrieving -several string attributes

For some agent implementations, it -may be more efficient to retrieve several string attributes for a content -object in one function call. The ContentAccess::RStringAttributeSet object -is used here to provide a way to request and store several attributes.

The -following example query three attributes using the CManager API:

// 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); - }
+ + + + + +Content +object attributes +

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.

+
Generic attributes

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.

These standardised +attributes are given by the enumeration ContentAccess::TAttribute. +It is possible for agents to extend this set of attributes, starting from EAgentSpecificAttributeBase.

The +attribute functions are implemented in ContentAccess::CContent, ContentAccess::CData and ContentAccess::CManager.

Retrieving a single attribute

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.

It is possible that the attribute may +not make sense for a particular content object. In that case, the agent will +return a KErrCANotSupported error. If an attempt is made +to retrieve the attributes of a content object that does not exist, the agent +will return KErrNotFound.

The following code fragment +illustrates how to retrieve an attribute for a particular object within a +content file.

// 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 + }

Retrieving several attributes

For some +agent implementations it may be more efficient to retrieve all the attributes +for a content object in one function call. The ContentAccess::RAttributeSet object +is used here to provide a way to request and store several attributes.

Querying +two attributes using the CManager API would look like the +following:

// 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 + }
+
Generic string attributes

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.

The string attributes +are standardised by the ContentAccess::TStringAttribute enumeration. +This allows applications to request information such as the MIME type in a +generic way for all agents.

Agents can extend this mechanism to provide +agent specific attributes starting at EAgentSpecificStringAttributeBase. +If the Agent does not support this attribute, it returns KErrCANotSupported.

Retrieving +several string attributes

For some agent implementations, it +may be more efficient to retrieve several string attributes for a content +object in one function call. The ContentAccess::RStringAttributeSet object +is used here to provide a way to request and store several attributes.

The +following example query three attributes using the CManager API:

// 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); + }
\ No newline at end of file