|
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 "Symbian Foundation License v1.0" |
|
5 // which accompanies this distribution, and is available |
|
6 // at the URL "http://www.symbianfoundation.org/legal/sfl-v10.html". |
|
7 // |
|
8 // Initial Contributors: |
|
9 // Nokia Corporation - initial contribution. |
|
10 // |
|
11 // Contributors: |
|
12 // |
|
13 // Description: |
|
14 // <hr> |
|
15 // The Content Access Framework provides a common interface for applications to access content. |
|
16 // In effect it behaves as a switch between different agents, known as Content Access Agents. |
|
17 // Each agent is an ECOM plugin, which implements the Content Access Agent interface <code>0x10204740</code>. |
|
18 // This interface should be a static function that creates and returns an instance of a class derived |
|
19 // from <code>ContentAccess::CAgentFactory</code> (e.g. <code>ContentAccess::CF32AgentFactory</code>). |
|
20 // <code>static CAgentFactory* AgentImplementationFunction();</code> |
|
21 // for reading unprotected content files. If no other agent recognizes a file the F32 agent will be used |
|
22 // to read it. In effect, this is the same as opening the file using an <code>RFile</code>, but allows the application |
|
23 // to use the same code to read protected and unprotected content. |
|
24 // The following diagram illustrates the implementation of CAF with two fictitious agents (OMA and MPEG). |
|
25 // <hr> |
|
26 // The problem with this implementation is that all three agents are loaded into the application's process space, |
|
27 // which represents a security risk. The application could potentially access the key used to decrypt protected |
|
28 // content. |
|
29 // A better solution is to implement the parts of the agent that require access to encryption/decryption keys or |
|
30 // rights in a separate server process. When platform security is enabled the server implementation also allows |
|
31 // the APIs to be policed by the agent server DLL to ensure only applcations with the right capabilities will |
|
32 // have access to the content. |
|
33 // To improve performance any functionality that does not require access to keys or rights should be implemented |
|
34 // in the client side DLL. Client side functionality reduces the number of context switches the processor needs |
|
35 // to perform resulting in improved performance from the agent. |
|
36 // There is no need to implement the F32 agent in a server process since it is only used to access unprotected content. |
|
37 // <hr> |
|
38 // The following guidelines are suggested for implementing Client/Server agents, but may not be appropriate |
|
39 // for all agents. |
|
40 // <b> Client Side Functionality </b> |
|
41 // - Implement the Content Access Agent ECOM interface |
|
42 // - Browse the contents of files |
|
43 // - Retrieve attributes or meta-data from a file |
|
44 // - All functions requiring the agent to display a user interface or dialog |
|
45 // - File recognition (for client applications and Apparc MIME types) |
|
46 // - Marshall calls to the server side |
|
47 // <b> Server Side Functionality </b> |
|
48 // - Content Encryption (protecting plaintext) |
|
49 // - Content Decryption (reading DRM content) |
|
50 // - Manage, protect and store Rights |
|
51 // - Any potentially destructive operation such as deleting content or rights |
|
52 // - Notifications |
|
53 // - Capability Enforcement |
|
54 // <hr> |
|
55 // The APIs provided in this document indicate the functions that are likely to require a client |
|
56 // process to have DRM capability in order to use the functionality. The client process will only |
|
57 // need DRM capability if it attempts to read DRM content using an CAF agent that implements a DRM |
|
58 // protection scheme. |
|
59 // The capability can only be enforced by the CAF agent running in a separate server process, so it is the responsibility |
|
60 // of the agent to ensure the client process has the required capabilities. |
|
61 // <b>There are no capabilities required to use unprotected content.</b> |
|
62 // <hr> |
|
63 // CAF is used to read unprotected or DRM protected content. It is a client side DLL that must be linked with |
|
64 // the process using CAF. |
|
65 // The agents may run in separate processes and will not have the correct capabilities to open files in TCB or |
|
66 // server private directories using just a file name. These files must be opened by the process that owns the |
|
67 // file and an open \c RFile handle passed to CAF in order to read them. |
|
68 // <hr> |
|
69 // |
|
70 // |
|
71 |
|
72 |
|
73 |
|
74 /** |
|
75 @page CAFArchitecture Architecture |
|
76 - @ref ArchOverview |
|
77 - @ref CAFClientServer |
|
78 - @ref ClientServerImplementation |
|
79 - @ref CAFCapability |
|
80 - @ref UsingCAF |
|
81 @section ArchOverview Overview |
|
82 There is a special agent supplied by Symbian known as the @ref AboutF32Agent "F32Agent". This agent is used as a fallback |
|
83 @image html Architecture1.gif |
|
84 @section CAFClientServer Client / Server Agents |
|
85 @image html Architecture2.gif |
|
86 @section ClientServerImplementation Client / Server implementation guidelines |
|
87 @section CAFCapability DRM Capability |
|
88 @section UsingCAF Using CAF to read from other server private directories |
|
89 */ |