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: // <hr>
sl@0: // The Content Access Framework is at released status in Symbian OS v9.1
sl@0: // <hr>
sl@0: // The Symbian OS Content Access Framework (CAF) provides services that
sl@0: // enable agents to publish content in a generic manner that is easy for 
sl@0: // applications to use. 
sl@0: // Applications will access content the same way regardless of whether the
sl@0: // content is plain text, located in a server's private directory, or
sl@0: // DRM protected.
sl@0: // Content can be, for example, media files or a level in a game; applications
sl@0: // would be, for example, a video/sound player or an internet browser; 
sl@0: // DRM stands for Digital Rights Management.
sl@0: // <hr>
sl@0: // The CAF defines an ECom plug-in interface, for third-party CAF Agents. The interface
sl@0: // allows new agents to be integrated at a later date, dynamically if required. 
sl@0: // The specification for this interface can be found in <code>ContentAccess::CAgentFactory</code>.
sl@0: // CAF Agents can be written to provide the following functions:
sl@0: // The CAF framework does not provide any capability enforcement so it is the responsiblity 
sl@0: // of the agent to police access to the APIs. The agent can choose to deny some operations 
sl@0: // in the CAF API based upon application's capabilities or the agent's own policy relating 
sl@0: // to the use of that API. 
sl@0: // <hr>
sl@0: // <code>ContentAccess::CAgentFactory</code>. This is the ECom interface for a CAF Agent.
sl@0: // The agent's factory will produce products derived from:
sl@0: // -# <code>ContentAccess::CAgentContent</code>
sl@0: // -# <code>ContentAccess::CAgentData</code>
sl@0: // -# <code>ContentAccess::CAgentImportFile</code>
sl@0: // -# <code>ContentAccess::CAgentManager</code>
sl@0: // -# <code>ContentAccess::CAgentRightsManager</code>
sl@0: // These products provide the services described in the introduction (above) on a per 
sl@0: // agent basis.
sl@0: // <hr>
sl@0: // Generally, these APIs fall into four areas:
sl@0: // <b>Supplier API</b> 
sl@0: // The Supplier API is used to handle the delivery and transformation of content.
sl@0: // It can be used to transform DRM protected files when they arrive on a device into 
sl@0: // a form that allows them to be stored securely on the device.
sl@0: // It can also be used intercept content and ensure it is stored in an agent's private 
sl@0: // directory.
sl@0: // See the classes <code>ContentAccess::CSupplier</code> and <code>ContentAccess::CImportFile</code>
sl@0: // <b>Consumer API</b> 
sl@0: // Allows applications to read the content as if it were stored as plain text regardless
sl@0: // of how it is actually stored on the device. For instance it might be encrypted.
sl@0: // The consumer API will be used by applications rendering content and/or multimedia 
sl@0: // plug-ins. By rendering we mean reading data from a file, transforming it, then playing 
sl@0: // or displaying it on the device.
sl@0: // See the classes <code>ContentAccess::CContent</code> and <code>ContentAccess::CData</code>.
sl@0: // <b>Manager API</b> 
sl@0: // The management of files and content access agents.
sl@0: // See <code>ContentAccess::CManager</code>
sl@0: // <b>Rights Manager API</b> 
sl@0: // A generic API used to manage DRM rights within a particular DRM agent
sl@0: // See <code>ContentAccess::CRightsManager</code>
sl@0: // <hr>
sl@0: // An archive file contains content objects and other containers within the file. Each
sl@0: // container within the file may contain more content objects or further containers.
sl@0: // Common examples of archive files are zip and tar files.
sl@0: // The Content Access Framework allows applications to open archive files and read 
sl@0: // content from inside them. The content objects and containers inside the 
sl@0: // file can be traversed using the <code>ContentAccess::CContent</code> class. 
sl@0: // This class allows applications to use the content within these container files 
sl@0: // without needing to understand any specifics of the compression or storage mechanism 
sl@0: // used by the archive.
sl@0: // <hr>
sl@0: // The Content Access Framework also provides an abstact way to access DRM protected 
sl@0: // content. An agent can be designed to implement a DRM scheme.
sl@0: // Applications use DRM protected files in the same way they would use any other file. 
sl@0: // The agent enforces the rights applied to the content. Also, it prevents access when rights
sl@0: // have expired or if the file is accessed by applications without DRM capability.
sl@0: // To enforce the protection of the content the agent must know what the client intends 
sl@0: // to do with the content once it has read the plain-text version of that content. Therefore, applications must 
sl@0: // Applications should \b always specify their intent, whether or not they will using DRM protected content. 
sl@0: // Non-DRM agents will just ignore the call, but it means the application does not need to treat DRM content 
sl@0: // as a special case.
sl@0: // One occasion where applications do need to treat DRM as a special case is where User Interface menu 
sl@0: // Applications can use the <code>GetAttribute()</code> functions to determine whether the operation is allowed on any 
sl@0: // given content object.
sl@0: // Finally any application or plug-in that reads DRM content must handle the unencrypted version of 
sl@0: // the content responsibly. Only applications proven to work this way will be given the DRM capability. 
sl@0: // <hr>
sl@0: // The evaluation of DRM rights hinges on the correct supply of 'DRM
sl@0: // Intent' from the trusted rendering application to the Content Access
sl@0: // Framework. The framework provides a number of options so that the
sl@0: // application can query and evaluate rights appropriately. 
sl@0: // Briefly, the CAF allows a renderer to:
sl@0: // - <b>Evalute intent</b> \n
sl@0: // e.g., ask the question "Could I play this now if I wanted to?". \n
sl@0: // Here, the ability is queried, but no stateful rights modifications are made.
sl@0: // - <b>Execute intent</b> \n
sl@0: // e.g., indicate "I have played this now". \n
sl@0: // In this example, the CAF would instruct the agent to evaluate and process
sl@0: // the rights, thus modifying any stateful rights 
sl@0: // (i.e., rights that have state, e.g. content that has an expiry date or content that can only be played three times, say).
sl@0: // Essentially, renders will begin by evaluating intent when the \c CData object
sl@0: // is created. When the content has been rendered successfully, they will execute 
sl@0: // the intent to ensure that stateful rights are then processed.
sl@0: // The recommended intent values (for renders and agents to support) are given in <code>ContentAccess::TIntent</code>:
sl@0: // - \c EPeek: Do not process or evaluate rights in any way
sl@0: // - \c EPlay: Play the target content (OMA)
sl@0: // - \c Eview: View the target content (OMA)
sl@0: // - \c EExecute: Execute the target content (OMA). Note: only supported in
sl@0: // a Java context
sl@0: // - \c EPrint: Print the target content (OMA)
sl@0: // - \c EPause: Pause content playback
sl@0: // - \c EContinue: Continue content playback
sl@0: // - \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.
sl@0: // <hr>
sl@0: // The F32 Agent provides access to unprotected files. It is really just a wrapper around <code>RFile</code>.
sl@0: // The Content Access Framework treats the F32 agent as a special case. If no other suitable 
sl@0: // agent is responsible for a file or directory the F32 Agent will be used. 
sl@0: // The F32 Agent runs in the same process and thread as the calling application so any 
sl@0: // file operations it performs will be limited to the file operations permitted for 
sl@0: // the calling application's process
sl@0: // <hr>
sl@0: // Some agents may provide access to files stored in their private directory. They
sl@0: // can advertise the files' existence to applications through their implementation 
sl@0: // of the <code>ContentAccess::CAgentManager::GetDir()</code> function.
sl@0: // In the file system the private directories have the format 
sl@0: // <code>\\private\\xxxxxxxx\\directory_1\\...directory_n\\filename.ext</code>
sl@0: // where <code>xxxxxxxx</code> is the UID of the agent.
sl@0: // CAF will translate that path so applications see the file as:
sl@0: // <code>\\private\\agent_name\\directory_1\\...directory_n\\filename.ext</code>
sl@0: // where <code>agent_name</code> is the name of the agent.
sl@0: // When an application opens a file stored in the private directory, CAF selects the 
sl@0: // agent which handles that content based upon the name in the path. If the file is not 
sl@0: // stored in a private directory, CAF asks each of the agents in turn whether they support 
sl@0: // the file. If no agent supports the file, it will be read as plaintext using the <code>F32Agent</code>.
sl@0: // <hr>
sl@0: // - <code>CAF.DLL</code>        - Content Access Framework (the application level APIs)
sl@0: // - <code>CAFUTILS.DLL</code>   - Utility classes used by agents, applications and CAF itself
sl@0: // - <code>F32AGENT.DLL</code>   - Agent for reading unprotected files
sl@0: // - <code>F32AGENTUI.DLL</code> - Agent for reading unprotected files
sl@0: // - <code>RECCAF.DLL</code>     - Data Recognizer for all agents within the Content Access Framework
sl@0: // <hr>
sl@0: // 
sl@0: //
sl@0: 
sl@0: /**
sl@0:  @page CAFIntroduction Introduction
sl@0:  @section CAF_Contents Contents
sl@0:  - @ref CAF_Status
sl@0:  - @ref CAF_Intro
sl@0:  - @ref CAF_Agents
sl@0:  - @ref CAF_Agent_Interfaces
sl@0:  - @ref CAFAPIs
sl@0:  - @ref AboutArchives
sl@0:  - @ref AboutDRM
sl@0:  - @ref CAF_Intent
sl@0:  - @ref AboutF32Agent
sl@0:  - @ref AboutPrivDir
sl@0:  - @ref CAF_Delivery
sl@0:  @section CAF_Status Status
sl@0:  @section CAF_Intro Overview
sl@0:  @section CAF_Agents CAF Agents
sl@0:  @li Indirect access to a private server directory
sl@0:  @li Plain text access to protected content (even if the content is encrypted)
sl@0:  @section CAF_Agent_Interfaces Agent Interfaces
sl@0:  A CAF agent @e must implement a concrete factory derived from 
sl@0:  @section CAFAPIs Content Access Framework APIs
sl@0:  @section AboutArchives Access to content within archive files
sl@0:  @section AboutDRM Digital Rights Management (DRM)
sl@0:  specify their intent before using DRM protected content, see @ref CAF_Intent. 
sl@0:  items may need to be disabled. For example, @e save or <i>send via Bluetooth</i> may not be permitted. 
sl@0:  @section CAF_Intent DRM Intent
sl@0:  @section AboutF32Agent The F32 Agent
sl@0:  @section AboutPrivDir Sharing Content in a Private Directory
sl@0:  @section CAF_Delivery Delivery
sl@0: */