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