// 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

*/