--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/contentmgmt/contentaccessfwfordrm/engineering/dox/Architecture.dox Wed Jul 08 11:25:26 2009 +0100
@@ -0,0 +1,89 @@
+// Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
+// All rights reserved.
+// This component and the accompanying materials are made available
+// under the terms of the License "Symbian Foundation License v1.0"
+// which accompanies this distribution, and is available
+// at the URL "http://www.symbianfoundation.org/legal/sfl-v10.html".
+//
+// Initial Contributors:
+// Nokia Corporation - initial contribution.
+//
+// Contributors:
+//
+// Description:
+// <hr>
+// The Content Access Framework provides a common interface for applications to access content.
+// In effect it behaves as a switch between different agents, known as Content Access Agents.
+// Each agent is an ECOM plugin, which implements the Content Access Agent interface <code>0x10204740</code>.
+// This interface should be a static function that creates and returns an instance of a class derived
+// from <code>ContentAccess::CAgentFactory</code> (e.g. <code>ContentAccess::CF32AgentFactory</code>).
+// <code>static CAgentFactory* AgentImplementationFunction();</code>
+// for reading unprotected content files. If no other agent recognizes a file the F32 agent will be used
+// to read it. In effect, this is the same as opening the file using an <code>RFile</code>, but allows the application
+// to use the same code to read protected and unprotected content.
+// The following diagram illustrates the implementation of CAF with two fictitious agents (OMA and MPEG).
+// <hr>
+// The problem with this implementation is that all three agents are loaded into the application's process space,
+// which represents a security risk. The application could potentially access the key used to decrypt protected
+// content.
+// A better solution is to implement the parts of the agent that require access to encryption/decryption keys or
+// rights in a separate server process. When platform security is enabled the server implementation also allows
+// the APIs to be policed by the agent server DLL to ensure only applcations with the right capabilities will
+// have access to the content.
+// To improve performance any functionality that does not require access to keys or rights should be implemented
+// in the client side DLL. Client side functionality reduces the number of context switches the processor needs
+// to perform resulting in improved performance from the agent.
+// There is no need to implement the F32 agent in a server process since it is only used to access unprotected content.
+// <hr>
+// The following guidelines are suggested for implementing Client/Server agents, but may not be appropriate
+// for all agents.
+// <b> Client Side Functionality </b>
+// - Implement the Content Access Agent ECOM interface
+// - Browse the contents of files
+// - Retrieve attributes or meta-data from a file
+// - All functions requiring the agent to display a user interface or dialog
+// - File recognition (for client applications and Apparc MIME types)
+// - Marshall calls to the server side
+// <b> Server Side Functionality </b>
+// - Content Encryption (protecting plaintext)
+// - Content Decryption (reading DRM content)
+// - Manage, protect and store Rights
+// - Any potentially destructive operation such as deleting content or rights
+// - Notifications
+// - Capability Enforcement
+// <hr>
+// The APIs provided in this document indicate the functions that are likely to require a client
+// process to have DRM capability in order to use the functionality. The client process will only
+// need DRM capability if it attempts to read DRM content using an CAF agent that implements a DRM
+// protection scheme.
+// The capability can only be enforced by the CAF agent running in a separate server process, so it is the responsibility
+// of the agent to ensure the client process has the required capabilities.
+// <b>There are no capabilities required to use unprotected content.</b>
+// <hr>
+// CAF is used to read unprotected or DRM protected content. It is a client side DLL that must be linked with
+// the process using CAF.
+// The agents may run in separate processes and will not have the correct capabilities to open files in TCB or
+// server private directories using just a file name. These files must be opened by the process that owns the
+// file and an open \c RFile handle passed to CAF in order to read them.
+// <hr>
+//
+//
+
+
+
+/**
+ @page CAFArchitecture Architecture
+ - @ref ArchOverview
+ - @ref CAFClientServer
+ - @ref ClientServerImplementation
+ - @ref CAFCapability
+ - @ref UsingCAF
+ @section ArchOverview Overview
+ There is a special agent supplied by Symbian known as the @ref AboutF32Agent "F32Agent". This agent is used as a fallback
+ @image html Architecture1.gif
+ @section CAFClientServer Client / Server Agents
+ @image html Architecture2.gif
+ @section ClientServerImplementation Client / Server implementation guidelines
+ @section CAFCapability DRM Capability
+ @section UsingCAF Using CAF to read from other server private directories
+*/