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 // <hr> |
|
15 // The Content Access Framework is at released status in Symbian OS v9.1 |
|
16 // <hr> |
|
17 // The Symbian OS Content Access Framework (CAF) provides services that |
|
18 // enable agents to publish content in a generic manner that is easy for |
|
19 // applications to use. |
|
20 // Applications will access content the same way regardless of whether the |
|
21 // content is plain text, located in a server's private directory, or |
|
22 // DRM protected. |
|
23 // Content can be, for example, media files or a level in a game; applications |
|
24 // would be, for example, a video/sound player or an internet browser; |
|
25 // DRM stands for Digital Rights Management. |
|
26 // <hr> |
|
27 // The CAF defines an ECom plug-in interface, for third-party CAF Agents. The interface |
|
28 // allows new agents to be integrated at a later date, dynamically if required. |
|
29 // The specification for this interface can be found in <code>ContentAccess::CAgentFactory</code>. |
|
30 // CAF Agents can be written to provide the following functions: |
|
31 // The CAF framework does not provide any capability enforcement so it is the responsiblity |
|
32 // of the agent to police access to the APIs. The agent can choose to deny some operations |
|
33 // in the CAF API based upon application's capabilities or the agent's own policy relating |
|
34 // to the use of that API. |
|
35 // <hr> |
|
36 // <code>ContentAccess::CAgentFactory</code>. This is the ECom interface for a CAF Agent. |
|
37 // The agent's factory will produce products derived from: |
|
38 // -# <code>ContentAccess::CAgentContent</code> |
|
39 // -# <code>ContentAccess::CAgentData</code> |
|
40 // -# <code>ContentAccess::CAgentImportFile</code> |
|
41 // -# <code>ContentAccess::CAgentManager</code> |
|
42 // -# <code>ContentAccess::CAgentRightsManager</code> |
|
43 // These products provide the services described in the introduction (above) on a per |
|
44 // agent basis. |
|
45 // <hr> |
|
46 // Generally, these APIs fall into four areas: |
|
47 // <b>Supplier API</b> |
|
48 // The Supplier API is used to handle the delivery and transformation of content. |
|
49 // It can be used to transform DRM protected files when they arrive on a device into |
|
50 // a form that allows them to be stored securely on the device. |
|
51 // It can also be used intercept content and ensure it is stored in an agent's private |
|
52 // directory. |
|
53 // See the classes <code>ContentAccess::CSupplier</code> and <code>ContentAccess::CImportFile</code> |
|
54 // <b>Consumer API</b> |
|
55 // Allows applications to read the content as if it were stored as plain text regardless |
|
56 // of how it is actually stored on the device. For instance it might be encrypted. |
|
57 // The consumer API will be used by applications rendering content and/or multimedia |
|
58 // plug-ins. By rendering we mean reading data from a file, transforming it, then playing |
|
59 // or displaying it on the device. |
|
60 // See the classes <code>ContentAccess::CContent</code> and <code>ContentAccess::CData</code>. |
|
61 // <b>Manager API</b> |
|
62 // The management of files and content access agents. |
|
63 // See <code>ContentAccess::CManager</code> |
|
64 // <b>Rights Manager API</b> |
|
65 // A generic API used to manage DRM rights within a particular DRM agent |
|
66 // See <code>ContentAccess::CRightsManager</code> |
|
67 // <hr> |
|
68 // An archive file contains content objects and other containers within the file. Each |
|
69 // container within the file may contain more content objects or further containers. |
|
70 // Common examples of archive files are zip and tar files. |
|
71 // The Content Access Framework allows applications to open archive files and read |
|
72 // content from inside them. The content objects and containers inside the |
|
73 // file can be traversed using the <code>ContentAccess::CContent</code> class. |
|
74 // This class allows applications to use the content within these container files |
|
75 // without needing to understand any specifics of the compression or storage mechanism |
|
76 // used by the archive. |
|
77 // <hr> |
|
78 // The Content Access Framework also provides an abstact way to access DRM protected |
|
79 // content. An agent can be designed to implement a DRM scheme. |
|
80 // Applications use DRM protected files in the same way they would use any other file. |
|
81 // The agent enforces the rights applied to the content. Also, it prevents access when rights |
|
82 // have expired or if the file is accessed by applications without DRM capability. |
|
83 // To enforce the protection of the content the agent must know what the client intends |
|
84 // to do with the content once it has read the plain-text version of that content. Therefore, applications must |
|
85 // Applications should \b always specify their intent, whether or not they will using DRM protected content. |
|
86 // Non-DRM agents will just ignore the call, but it means the application does not need to treat DRM content |
|
87 // as a special case. |
|
88 // One occasion where applications do need to treat DRM as a special case is where User Interface menu |
|
89 // Applications can use the <code>GetAttribute()</code> functions to determine whether the operation is allowed on any |
|
90 // given content object. |
|
91 // Finally any application or plug-in that reads DRM content must handle the unencrypted version of |
|
92 // the content responsibly. Only applications proven to work this way will be given the DRM capability. |
|
93 // <hr> |
|
94 // The evaluation of DRM rights hinges on the correct supply of 'DRM |
|
95 // Intent' from the trusted rendering application to the Content Access |
|
96 // Framework. The framework provides a number of options so that the |
|
97 // application can query and evaluate rights appropriately. |
|
98 // Briefly, the CAF allows a renderer to: |
|
99 // - <b>Evalute intent</b> \n |
|
100 // e.g., ask the question "Could I play this now if I wanted to?". \n |
|
101 // Here, the ability is queried, but no stateful rights modifications are made. |
|
102 // - <b>Execute intent</b> \n |
|
103 // e.g., indicate "I have played this now". \n |
|
104 // In this example, the CAF would instruct the agent to evaluate and process |
|
105 // the rights, thus modifying any stateful rights |
|
106 // (i.e., rights that have state, e.g. content that has an expiry date or content that can only be played three times, say). |
|
107 // Essentially, renders will begin by evaluating intent when the \c CData object |
|
108 // is created. When the content has been rendered successfully, they will execute |
|
109 // the intent to ensure that stateful rights are then processed. |
|
110 // The recommended intent values (for renders and agents to support) are given in <code>ContentAccess::TIntent</code>: |
|
111 // - \c EPeek: Do not process or evaluate rights in any way |
|
112 // - \c EPlay: Play the target content (OMA) |
|
113 // - \c Eview: View the target content (OMA) |
|
114 // - \c EExecute: Execute the target content (OMA). Note: only supported in |
|
115 // a Java context |
|
116 // - \c EPrint: Print the target content (OMA) |
|
117 // - \c EPause: Pause content playback |
|
118 // - \c EContinue: Continue content playback |
|
119 // - \c EUnknown: Client has no idea what the content will be used for. DRM Agents can deny this intent allowing only unprotected content to be accessed this way. |
|
120 // <hr> |
|
121 // The F32 Agent provides access to unprotected files. It is really just a wrapper around <code>RFile</code>. |
|
122 // The Content Access Framework treats the F32 agent as a special case. If no other suitable |
|
123 // agent is responsible for a file or directory the F32 Agent will be used. |
|
124 // The F32 Agent runs in the same process and thread as the calling application so any |
|
125 // file operations it performs will be limited to the file operations permitted for |
|
126 // the calling application's process |
|
127 // <hr> |
|
128 // Some agents may provide access to files stored in their private directory. They |
|
129 // can advertise the files' existence to applications through their implementation |
|
130 // of the <code>ContentAccess::CAgentManager::GetDir()</code> function. |
|
131 // In the file system the private directories have the format |
|
132 // <code>\\private\\xxxxxxxx\\directory_1\\...directory_n\\filename.ext</code> |
|
133 // where <code>xxxxxxxx</code> is the UID of the agent. |
|
134 // CAF will translate that path so applications see the file as: |
|
135 // <code>\\private\\agent_name\\directory_1\\...directory_n\\filename.ext</code> |
|
136 // where <code>agent_name</code> is the name of the agent. |
|
137 // When an application opens a file stored in the private directory, CAF selects the |
|
138 // agent which handles that content based upon the name in the path. If the file is not |
|
139 // stored in a private directory, CAF asks each of the agents in turn whether they support |
|
140 // the file. If no agent supports the file, it will be read as plaintext using the <code>F32Agent</code>. |
|
141 // <hr> |
|
142 // - <code>CAF.DLL</code> - Content Access Framework (the application level APIs) |
|
143 // - <code>CAFUTILS.DLL</code> - Utility classes used by agents, applications and CAF itself |
|
144 // - <code>F32AGENT.DLL</code> - Agent for reading unprotected files |
|
145 // - <code>F32AGENTUI.DLL</code> - Agent for reading unprotected files |
|
146 // - <code>RECCAF.DLL</code> - Data Recognizer for all agents within the Content Access Framework |
|
147 // <hr> |
|
148 // |
|
149 // |
|
150 |
|
151 /** |
|
152 @page CAFIntroduction Introduction |
|
153 @section CAF_Contents Contents |
|
154 - @ref CAF_Status |
|
155 - @ref CAF_Intro |
|
156 - @ref CAF_Agents |
|
157 - @ref CAF_Agent_Interfaces |
|
158 - @ref CAFAPIs |
|
159 - @ref AboutArchives |
|
160 - @ref AboutDRM |
|
161 - @ref CAF_Intent |
|
162 - @ref AboutF32Agent |
|
163 - @ref AboutPrivDir |
|
164 - @ref CAF_Delivery |
|
165 @section CAF_Status Status |
|
166 @section CAF_Intro Overview |
|
167 @section CAF_Agents CAF Agents |
|
168 @li Indirect access to a private server directory |
|
169 @li Plain text access to protected content (even if the content is encrypted) |
|
170 @section CAF_Agent_Interfaces Agent Interfaces |
|
171 A CAF agent @e must implement a concrete factory derived from |
|
172 @section CAFAPIs Content Access Framework APIs |
|
173 @section AboutArchives Access to content within archive files |
|
174 @section AboutDRM Digital Rights Management (DRM) |
|
175 specify their intent before using DRM protected content, see @ref CAF_Intent. |
|
176 items may need to be disabled. For example, @e save or <i>send via Bluetooth</i> may not be permitted. |
|
177 @section CAF_Intent DRM Intent |
|
178 @section AboutF32Agent The F32 Agent |
|
179 @section AboutPrivDir Sharing Content in a Private Directory |
|
180 @section CAF_Delivery Delivery |
|
181 */ |
|