os/security/contentmgmt/contentaccessfwfordrm/engineering/dox/CAFIntroduction.dox
1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/os/security/contentmgmt/contentaccessfwfordrm/engineering/dox/CAFIntroduction.dox Fri Jun 15 03:10:57 2012 +0200
1.3 @@ -0,0 +1,181 @@
1.4 +// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
1.5 +// All rights reserved.
1.6 +// This component and the accompanying materials are made available
1.7 +// under the terms of the License "Eclipse Public License v1.0"
1.8 +// which accompanies this distribution, and is available
1.9 +// at the URL "http://www.eclipse.org/legal/epl-v10.html".
1.10 +//
1.11 +// Initial Contributors:
1.12 +// Nokia Corporation - initial contribution.
1.13 +//
1.14 +// Contributors:
1.15 +//
1.16 +// Description:
1.17 +// <hr>
1.18 +// The Content Access Framework is at released status in Symbian OS v9.1
1.19 +// <hr>
1.20 +// The Symbian OS Content Access Framework (CAF) provides services that
1.21 +// enable agents to publish content in a generic manner that is easy for
1.22 +// applications to use.
1.23 +// Applications will access content the same way regardless of whether the
1.24 +// content is plain text, located in a server's private directory, or
1.25 +// DRM protected.
1.26 +// Content can be, for example, media files or a level in a game; applications
1.27 +// would be, for example, a video/sound player or an internet browser;
1.28 +// DRM stands for Digital Rights Management.
1.29 +// <hr>
1.30 +// The CAF defines an ECom plug-in interface, for third-party CAF Agents. The interface
1.31 +// allows new agents to be integrated at a later date, dynamically if required.
1.32 +// The specification for this interface can be found in <code>ContentAccess::CAgentFactory</code>.
1.33 +// CAF Agents can be written to provide the following functions:
1.34 +// The CAF framework does not provide any capability enforcement so it is the responsiblity
1.35 +// of the agent to police access to the APIs. The agent can choose to deny some operations
1.36 +// in the CAF API based upon application's capabilities or the agent's own policy relating
1.37 +// to the use of that API.
1.38 +// <hr>
1.39 +// <code>ContentAccess::CAgentFactory</code>. This is the ECom interface for a CAF Agent.
1.40 +// The agent's factory will produce products derived from:
1.41 +// -# <code>ContentAccess::CAgentContent</code>
1.42 +// -# <code>ContentAccess::CAgentData</code>
1.43 +// -# <code>ContentAccess::CAgentImportFile</code>
1.44 +// -# <code>ContentAccess::CAgentManager</code>
1.45 +// -# <code>ContentAccess::CAgentRightsManager</code>
1.46 +// These products provide the services described in the introduction (above) on a per
1.47 +// agent basis.
1.48 +// <hr>
1.49 +// Generally, these APIs fall into four areas:
1.50 +// <b>Supplier API</b>
1.51 +// The Supplier API is used to handle the delivery and transformation of content.
1.52 +// It can be used to transform DRM protected files when they arrive on a device into
1.53 +// a form that allows them to be stored securely on the device.
1.54 +// It can also be used intercept content and ensure it is stored in an agent's private
1.55 +// directory.
1.56 +// See the classes <code>ContentAccess::CSupplier</code> and <code>ContentAccess::CImportFile</code>
1.57 +// <b>Consumer API</b>
1.58 +// Allows applications to read the content as if it were stored as plain text regardless
1.59 +// of how it is actually stored on the device. For instance it might be encrypted.
1.60 +// The consumer API will be used by applications rendering content and/or multimedia
1.61 +// plug-ins. By rendering we mean reading data from a file, transforming it, then playing
1.62 +// or displaying it on the device.
1.63 +// See the classes <code>ContentAccess::CContent</code> and <code>ContentAccess::CData</code>.
1.64 +// <b>Manager API</b>
1.65 +// The management of files and content access agents.
1.66 +// See <code>ContentAccess::CManager</code>
1.67 +// <b>Rights Manager API</b>
1.68 +// A generic API used to manage DRM rights within a particular DRM agent
1.69 +// See <code>ContentAccess::CRightsManager</code>
1.70 +// <hr>
1.71 +// An archive file contains content objects and other containers within the file. Each
1.72 +// container within the file may contain more content objects or further containers.
1.73 +// Common examples of archive files are zip and tar files.
1.74 +// The Content Access Framework allows applications to open archive files and read
1.75 +// content from inside them. The content objects and containers inside the
1.76 +// file can be traversed using the <code>ContentAccess::CContent</code> class.
1.77 +// This class allows applications to use the content within these container files
1.78 +// without needing to understand any specifics of the compression or storage mechanism
1.79 +// used by the archive.
1.80 +// <hr>
1.81 +// The Content Access Framework also provides an abstact way to access DRM protected
1.82 +// content. An agent can be designed to implement a DRM scheme.
1.83 +// Applications use DRM protected files in the same way they would use any other file.
1.84 +// The agent enforces the rights applied to the content. Also, it prevents access when rights
1.85 +// have expired or if the file is accessed by applications without DRM capability.
1.86 +// To enforce the protection of the content the agent must know what the client intends
1.87 +// to do with the content once it has read the plain-text version of that content. Therefore, applications must
1.88 +// Applications should \b always specify their intent, whether or not they will using DRM protected content.
1.89 +// Non-DRM agents will just ignore the call, but it means the application does not need to treat DRM content
1.90 +// as a special case.
1.91 +// One occasion where applications do need to treat DRM as a special case is where User Interface menu
1.92 +// Applications can use the <code>GetAttribute()</code> functions to determine whether the operation is allowed on any
1.93 +// given content object.
1.94 +// Finally any application or plug-in that reads DRM content must handle the unencrypted version of
1.95 +// the content responsibly. Only applications proven to work this way will be given the DRM capability.
1.96 +// <hr>
1.97 +// The evaluation of DRM rights hinges on the correct supply of 'DRM
1.98 +// Intent' from the trusted rendering application to the Content Access
1.99 +// Framework. The framework provides a number of options so that the
1.100 +// application can query and evaluate rights appropriately.
1.101 +// Briefly, the CAF allows a renderer to:
1.102 +// - <b>Evalute intent</b> \n
1.103 +// e.g., ask the question "Could I play this now if I wanted to?". \n
1.104 +// Here, the ability is queried, but no stateful rights modifications are made.
1.105 +// - <b>Execute intent</b> \n
1.106 +// e.g., indicate "I have played this now". \n
1.107 +// In this example, the CAF would instruct the agent to evaluate and process
1.108 +// the rights, thus modifying any stateful rights
1.109 +// (i.e., rights that have state, e.g. content that has an expiry date or content that can only be played three times, say).
1.110 +// Essentially, renders will begin by evaluating intent when the \c CData object
1.111 +// is created. When the content has been rendered successfully, they will execute
1.112 +// the intent to ensure that stateful rights are then processed.
1.113 +// The recommended intent values (for renders and agents to support) are given in <code>ContentAccess::TIntent</code>:
1.114 +// - \c EPeek: Do not process or evaluate rights in any way
1.115 +// - \c EPlay: Play the target content (OMA)
1.116 +// - \c Eview: View the target content (OMA)
1.117 +// - \c EExecute: Execute the target content (OMA). Note: only supported in
1.118 +// a Java context
1.119 +// - \c EPrint: Print the target content (OMA)
1.120 +// - \c EPause: Pause content playback
1.121 +// - \c EContinue: Continue content playback
1.122 +// - \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.
1.123 +// <hr>
1.124 +// The F32 Agent provides access to unprotected files. It is really just a wrapper around <code>RFile</code>.
1.125 +// The Content Access Framework treats the F32 agent as a special case. If no other suitable
1.126 +// agent is responsible for a file or directory the F32 Agent will be used.
1.127 +// The F32 Agent runs in the same process and thread as the calling application so any
1.128 +// file operations it performs will be limited to the file operations permitted for
1.129 +// the calling application's process
1.130 +// <hr>
1.131 +// Some agents may provide access to files stored in their private directory. They
1.132 +// can advertise the files' existence to applications through their implementation
1.133 +// of the <code>ContentAccess::CAgentManager::GetDir()</code> function.
1.134 +// In the file system the private directories have the format
1.135 +// <code>\\private\\xxxxxxxx\\directory_1\\...directory_n\\filename.ext</code>
1.136 +// where <code>xxxxxxxx</code> is the UID of the agent.
1.137 +// CAF will translate that path so applications see the file as:
1.138 +// <code>\\private\\agent_name\\directory_1\\...directory_n\\filename.ext</code>
1.139 +// where <code>agent_name</code> is the name of the agent.
1.140 +// When an application opens a file stored in the private directory, CAF selects the
1.141 +// agent which handles that content based upon the name in the path. If the file is not
1.142 +// stored in a private directory, CAF asks each of the agents in turn whether they support
1.143 +// the file. If no agent supports the file, it will be read as plaintext using the <code>F32Agent</code>.
1.144 +// <hr>
1.145 +// - <code>CAF.DLL</code> - Content Access Framework (the application level APIs)
1.146 +// - <code>CAFUTILS.DLL</code> - Utility classes used by agents, applications and CAF itself
1.147 +// - <code>F32AGENT.DLL</code> - Agent for reading unprotected files
1.148 +// - <code>F32AGENTUI.DLL</code> - Agent for reading unprotected files
1.149 +// - <code>RECCAF.DLL</code> - Data Recognizer for all agents within the Content Access Framework
1.150 +// <hr>
1.151 +//
1.152 +//
1.153 +
1.154 +/**
1.155 + @page CAFIntroduction Introduction
1.156 + @section CAF_Contents Contents
1.157 + - @ref CAF_Status
1.158 + - @ref CAF_Intro
1.159 + - @ref CAF_Agents
1.160 + - @ref CAF_Agent_Interfaces
1.161 + - @ref CAFAPIs
1.162 + - @ref AboutArchives
1.163 + - @ref AboutDRM
1.164 + - @ref CAF_Intent
1.165 + - @ref AboutF32Agent
1.166 + - @ref AboutPrivDir
1.167 + - @ref CAF_Delivery
1.168 + @section CAF_Status Status
1.169 + @section CAF_Intro Overview
1.170 + @section CAF_Agents CAF Agents
1.171 + @li Indirect access to a private server directory
1.172 + @li Plain text access to protected content (even if the content is encrypted)
1.173 + @section CAF_Agent_Interfaces Agent Interfaces
1.174 + A CAF agent @e must implement a concrete factory derived from
1.175 + @section CAFAPIs Content Access Framework APIs
1.176 + @section AboutArchives Access to content within archive files
1.177 + @section AboutDRM Digital Rights Management (DRM)
1.178 + specify their intent before using DRM protected content, see @ref CAF_Intent.
1.179 + items may need to be disabled. For example, @e save or <i>send via Bluetooth</i> may not be permitted.
1.180 + @section CAF_Intent DRM Intent
1.181 + @section AboutF32Agent The F32 Agent
1.182 + @section AboutPrivDir Sharing Content in a Private Directory
1.183 + @section CAF_Delivery Delivery
1.184 +*/