1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
2 // All rights reserved. |
|
3 // This component and the accompanying materials are made available |
|
4 // under the terms of the License "Eclipse Public License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // Each of these objects may have properties or attributes associated with it. This section |
|
15 // outlines how applications can retrieve these using the CAF API. |
|
16 // <hr> |
|
17 // Different agents may use different terms to describe the same concept. Generic attributes provide a |
|
18 // way for applications to query standardised information about a content object. |
|
19 // These standardised attributes are given by the enumeration <code>ContentAccess::TAttribute</code>. It is possible |
|
20 // for agents to extend this set of attributes, starting from <code>EAgentSpecificAttributeBase</code>. |
|
21 // The attribute functions are implemented in <code>ContentAccess::CContent</code>, <code>ContentAccess::CData</code> and |
|
22 // <code>ContentAccess::CManager</code>. |
|
23 // <b> Retrieving a Single Attribute </b> |
|
24 // The attributes of one content object in a file may not necessarily be the same as the |
|
25 // attributes of other content objects within the same file. Attributes relate to a single |
|
26 // content object within a file. |
|
27 // It is possible that the attribute may not make sense for a particular content object. In that |
|
28 // case the agent will return an error <code>KErrCANotSupported</code>. If an attempt is made to |
|
29 // retrieve the attributes of a content object that does not exist the agent will return <code>KErrNotFound</code>. |
|
30 // The following code fragment illustrates how to retrieve an attribute for a particular |
|
31 // object within a content file. |
|
32 // CContent* content = CContent::NewL(uri); |
|
33 // // check if DRM rights are pending for the object specified by uniqueId |
|
34 // TInt attributeValue; |
|
35 // TInt err = content->GetAttribute(ERightsPending, attributeValue, uniqueId); |
|
36 // if(err == KErrNone) |
|
37 // // Check the value of the attribute |
|
38 // if(attributeValue == ETrue) |
|
39 // // Rights are pending, display waiting for rights countdown |
|
40 // else if(attributeValue == EFalse) |
|
41 // // Rights are not pending |
|
42 // else if(err == KErrCANotSupported) |
|
43 // // This attribute does not apply to this content object |
|
44 // else if(err == KErrNotFound) |
|
45 // // Cannot find the object specified by the given uniqueId |
|
46 // else if (err != KErrPermissionDenied) |
|
47 // // Unknown error |
|
48 // User::Leave(err); |
|
49 // <b> Retrieving Several Attributes </b> |
|
50 // For some agent implementations it may be more efficient to retrieve all the attributes for a content |
|
51 // object in one function call. The <code>ContentAccess::RAttributeSet</code> object is used here to provide a way to |
|
52 // request and store several attributes. |
|
53 // Querying two attributes using the CManager API would look like the following: |
|
54 // // Agent manager |
|
55 // CManager *manager = CManager::NewLC(); |
|
56 // // Prepare the attributes to query using the CAttributeSet object |
|
57 // RAttributeSet attributeSet; |
|
58 // CleanupClosePushL(attributeSet); |
|
59 // attributeSet.AddL(EProtected); |
|
60 // attributeSet.AddL(ECanView); |
|
61 // // Retrieve the attribute values from the agent |
|
62 // User::LeaveIfError(manager->GetAttributeSet(attributeSet, virtualPath)); |
|
63 // // Check if the content object is protected |
|
64 // TInt attributeValue; |
|
65 // TInt err = attributeSet.GetValue(EProtected, attributeValue); |
|
66 // if(err == KErrNone && attributeValue) |
|
67 // // content object is DRM protected |
|
68 // // Check if the content object can be display on screen |
|
69 // TInt err = attributeSet.GetValue(ECanView, attributeValue); |
|
70 // if(err == KErrNone && attributeValue) |
|
71 // // content object has rights that allow it to be displayed on screen |
|
72 // // Finished |
|
73 // CleanupStack::PopAndDestroy(2); // manager, attributeSet |
|
74 // <hr> |
|
75 // String attributes are similar to the attributes described above except the value associated |
|
76 // with the attribute is a string. A good example of where a string attribute is required is the |
|
77 // MIME type of a content object within a file. |
|
78 // The string attributes are standardised by the <code>ContentAccess::TStringAttribute</code> enumeration. This |
|
79 // allows applications to request information such as the MIME type in a generic way for all agents. |
|
80 // Agents can extend this mechanism to provide agent specific attributes starting at |
|
81 // <code>EAgentSpecificStringAttributeBase</code>. |
|
82 // The following example finds the author of a content object. |
|
83 // CContent* content = CContent::NewL(uri); |
|
84 // // define a buffer to store the attribute value string |
|
85 // TBuf <100> buf; |
|
86 // // retrieve the attribute |
|
87 // err = content->GetAttribute(EAuthor, authorBuffer, uniqueId); |
|
88 // // Display the authors name on screen |
|
89 // if (err == KErrNone) |
|
90 // DisplayAuthor(buf); |
|
91 // If the Agent does not support this attribute, it will return <code>KErrCANotSupported</code>. |
|
92 // <b> Retrieving Several String Attributes </b> |
|
93 // For some agent implementations it may be more efficient to retrieve several string attributes for a content |
|
94 // object in one function call. The <code>ContentAccess::RStringAttributeSet</code> object is used here to provide a way to |
|
95 // request and store several attributes. |
|
96 // Querying three attributes using the CManager API would look like the following: |
|
97 // CManager *manager = CManager::NewLC(); |
|
98 // // Prepare the attributes to query using the CAttributeSet object |
|
99 // RStringAttributeSet stringAttributeSet; |
|
100 // CleanupClosePushL(stringAttributeSet); |
|
101 // stringAttributeSet.AddL(ETitle); |
|
102 // stringAttributeSet.AddL(EAuthor); |
|
103 // stringAttributeSet.AddL(EDescription); |
|
104 // // Retrieve the attribute values from the agent |
|
105 // User::LeaveIfError(manager->GetStringAttributeSet(stringAttributeSet, virtualPath)); |
|
106 // // Display the values |
|
107 // TBuf <256> value; |
|
108 // TInt err = stringAttributeSet.GetValue(ETitle, value); |
|
109 // if(err == KErrNone) |
|
110 // Printf("Title : %s", value); |
|
111 // err = stringAttributeSet.GetValue(EAuthor, value); |
|
112 // if(err == KErrNone) |
|
113 // Printf("Author : %s", value); |
|
114 // err = stringAttributeSet.GetValue(EDescription, value); |
|
115 // if(err == KErrNone) |
|
116 // Printf("Description : %s", value); |
|
117 // // Finished |
|
118 // CleanupStack::PopAndDestroy(2); // manager, stringAttributeSet |
|
119 // <hr> |
|
120 // Some agents may expose meta data so they can be read using a \c CData object. The format |
|
121 // of these meta-data objects is not specified by the Content Access Framework but could |
|
122 // be useful for applications familiar with the agent to read meta data this way. |
|
123 // \c CData objects for agent specific meta-data can be opened in the same way content objects |
|
124 // are opened using the <code>ContentAccess::CContent::OpenContentL()</code> function. |
|
125 // CContent* content = CContent::NewLC(uri); |
|
126 // // Create an array to store the embedded objects |
|
127 // RStreamablePtrArray<CEmbeddedObject> myArray; |
|
128 // CleanupClosePushL(myArray); |
|
129 // // Get the embedded "Agent Specific" objects in the current container |
|
130 // content->GetEmbeddedObjectsL(myArray, EAgentSpecificObject); |
|
131 // // Get the unique Id of the first meta-data object |
|
132 // TPtrC aUniqueId = myArray[0]->UniqueId(); |
|
133 // // create a CData object to read the meta data |
|
134 // CData *myMetaData = content->OpenContentLC(EPeek, aUniqueId); |
|
135 // // Do something with the data |
|
136 // // Finished |
|
137 // CleanupStack::PopAndDestroy(3); // content, myArray, myMetaData |
|
138 // <hr> |
|
139 // |
|
140 // |
|
141 |
|
142 /** |
|
143 @page ContentAttributes Content Object Attributes |
|
144 As shown in the @ref CContentAPI "Consumer API", a file may consist of many content and container objects. |
|
145 - @ref CAFAttributes |
|
146 - @ref CAFStringAttributes |
|
147 - @ref CAFAgentSpecificMetaData |
|
148 @section CAFAttributes Generic Attributes |
|
149 @code |
|
150 @endcode |
|
151 @code |
|
152 @endcode |
|
153 @section CAFStringAttributes Generic String attributes |
|
154 @code |
|
155 @endcode |
|
156 @code |
|
157 @endcode |
|
158 @section CAFAgentSpecificMetaData Agent specific meta-data |
|
159 @code |
|
160 @endcode |
|
161 */ |
|