// 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 "Eclipse Public License v1.0"

 // which accompanies this distribution, and is available

 // at the URL "http://www.eclipse.org/legal/epl-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

 */