<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 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: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-84B6389A-55CC-53EB-8725-65F753FD7217" xml:lang="en"><title>Content

Access Framework Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The Content Access Framework (CAF) provides a common interface for applications

to access Digital Rights Management (DRM) protected content. An application

might be a video or sound player or an internet browser and DRM content might

be a media files or a game. </p>

<section><title>Purpose</title> <p>CAF provides a single point of access to

all functionality related to DRM-protected content. </p> <ul>

<li id="GUID-15DE43E1-3623-54FF-8AA5-0156D4809199"><p>Access to DRM-protected

content for content consumers, such as media players or software installers </p> </li>

<li id="GUID-CAD976B3-5AF4-53D2-B4C9-BB20D329AA88"><p>Management of DRM protected

content </p> </li>

<li id="GUID-FC614936-1F4A-557D-A61C-BF876050F5A2"><p>Import DRM protected

information </p> </li>

<li id="GUID-1DA7B843-171D-5C58-8157-B984C8218987"><p>Notification on DRM

related events, such as rights expiry </p> </li>

<li id="GUID-BE79AE4B-4DAD-5F91-A7BC-8FAC2143E858"><p>Implementation of new

DRM schemes </p> </li>

</ul> </section>

<section id="GUID-290C30C0-B088-534F-992E-CA2ED277F07D"><title>Key concepts

and terms</title> <dl>

<dlentry>

<dt>Content</dt>

<dd><p>Content is logically-coupled data such as a movie, a soundtrack or

a ringtone forming a content file. </p> </dd>

</dlentry>

</dl> <dl>

<dlentry>

<dt>Content consumer</dt>

<dd><p>Content consumers are applications such as media players or software

installers that access DRM-protected content. </p> </dd>

</dlentry>

</dl> <dl>

<dlentry>

<dt>Content access agent</dt>

<dd><p>A content access agent is an ECom plug-in which implements the CAF

interface and performs the following functions: </p> <ul>

<li id="GUID-96ACA45F-F89C-5F83-B2FC-FE19F7EEECB0"><p>Provides access to protected

content such as MPEG and MP3, and allows viewing them as plain text (even

if the content is encrypted). </p> </li>

<li id="GUID-2B5D35F4-71F7-52A2-A596-24817C68E769"><p>Provides indirect access

to a private server directory. </p> </li>

<li id="GUID-A2DA01FB-721E-5E9C-B61C-3A5E28034971"><p>Provides platform security

enforcement. CAF does not provide any capability enforcement so the agent

must police access to the APIs. The agent can choose to deny some operations

in the CAF API based upon both the application's capabilities and the agent's

policy. </p> </li>

</ul> </dd>

</dlentry>

</dl> <dl>

<dlentry>

<dt>F32 agent</dt>

<dd><p>The F32 agent provides access to unprotected files. CAF treats the

F32 agent as a special case. If no other agent is responsible for a file or

directory, the F32 Agent is used. </p> <p>The F32 agent runs in the same process

and thread as the calling application, so its file operations are limited

to the capability of the calling application's. </p> </dd>

</dlentry>

</dl> <dl>

<dlentry>

<dt>Handling and sharing content in a private directory </dt>

<dd><p>Few agents can provide access to files stored in their private directory.

They can share their files existence to applications through implementation

of the <xref href="GUID-D7457871-5361-3684-9A95-FBDB9C2689DD.dita#GUID-D7457871-5361-3684-9A95-FBDB9C2689DD/GUID-0306A1CE-9EAA-3008-A9D7-1AACA95A6081"><apiname>ContentAccess::CAgentManager::GetDir()</apiname></xref> function.

In the file system the private directories have the format: </p> <p> <codeph>\private\xxxxxxxx\directory_1\...directory_n\filename.ext</codeph> </p> <p>where <codeph>xxxxxxxx</codeph> is the UID of the agent. </p> <p>CAF

will translate that path so applications see the file as: </p> <p> <codeph>\private\agent_name\directory_1\...directory_n\filename.ext</codeph> </p> <p>where <codeph>agent_name</codeph> is the name of the agent. </p> <p>When

an application opens a file stored in the private directory, CAF selects the

agent which handles that content based upon the name in the path. If the file

is not stored in a private directory, CAF asks each of the agents in turn

whether they support the file. If no agent supports the file, it will be read

as plaintext using the F32Agent. </p> </dd>

</dlentry>

</dl> </section>

<section><title>Architecture</title> <p>CAF provides interfaces for applications

to read both unprotected and DRM protected content. It behaves as a switch

between different Content Access Agents. </p> <p>CAF uses a client-server

architecture. The CAF client DLL must be linked with the client process. CAF

agents can be implemented as plug-ins to the CAF client if they do not require

access to keys or rights. An agent requiring access to encryption or decryption

of keys, or rights must be implemented as a server-side plug-in. A server

side plug-in must ensure that only applications with the right capabilities

can access the content. </p> <p>Each agent is an ECOM plug-in implementing

the content access agent interface UID 0x10204740. The agents can run in separate

processes and need not have the capability to open files in the TCB or private

server directories using just a file name. Files must be opened by the process

that owns them and an open <xref href="GUID-BE0804F6-4375-3C8A-8C83-968F510466E0.dita"><apiname>RFile</apiname></xref> handle passed to CAF to

read it. </p> <p>In the following diagram the yellow blocks represent the

components provided by Symbian and the blue blocks represent the components

that must be implemented by device creators. </p> <fig id="GUID-40498A21-44F3-5250-9E02-3ACF30EC2BF9">

<title>              CAF Architecture            </title>

<image href="GUID-B93C26B8-D767-5341-A629-1A5714A20992_d0e614738_href.jpg" placement="inline"/>

</fig> <p> <b>Note</b>: The F32 agent is a client-side implementation as it

is used for accessing unprotected content only. </p> </section>

<section><title>Key classes</title> <p>The following table summarizes the

important classes provided by CAF: </p> <p> <b>Note</b>: The classes below

are defined within the namespace <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita"><apiname>ContentAccess</apiname></xref>  </p> <table id="GUID-7399345A-ADC8-57B1-B3D5-C8DD93F0F626">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Class</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-45942AF3-2D3E-3D22-88D0-904D70074357.dita"><apiname>CSupplier</apiname></xref>  </p> </entry>

<entry><p>Delivers and transforms content into a secure format for storing

it in the device </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-EF3C33C0-F02E-3C35-B289-3800631EDC3A.dita"><apiname>CContent</apiname></xref>  </p> </entry>

<entry><p>Provides read access to content (including protected content) stored

in a device. </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-7F3D9E35-A8FC-35A6-8036-23396BAADFDC.dita"><apiname>CManager</apiname></xref>  </p> </entry>

<entry><p>Manages files and content access agents </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-C4B8AE31-6ABD-3FEA-88DD-3B4EE13ACF49.dita"><apiname>CRightsManager</apiname></xref>  </p> </entry>

<entry><p>Manages DRM rights for a specific CAF agent </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-136D0282-4C73-33E9-B9D4-9CE92A33BF75.dita"><apiname>CData</apiname></xref>  </p> </entry>

<entry><p>Allows clients to read data from a content object </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-D90E390E-0A4F-357D-98BF-C445CC2E7EB0.dita"><apiname>CAgentFactory</apiname></xref>  </p> </entry>

<entry><p>Represents the ECom interface for a CAF Agent. A CAF agent must

implement a concrete factory derived from <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-798F4B18-D6AE-36B9-B03F-C1FC55266CB5"><apiname>ContentAccess::CAgentFactory</apiname></xref>. </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>The above APIs are grouped as follows: </p> <p><b>Supplier API </b> </p> <p>The

classes <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-0CE549BA-2F8C-3101-AD01-A1BF15C4EAE4"><apiname>ContentAccess::CSupplier</apiname></xref> and <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-E952CB96-3638-321A-B9BC-01C559FB8F4C"><apiname>ContentAccess::CImportFile</apiname></xref> together

represents the supplier API. </p> <p>The Supplier API handles the delivery

and transformation of content. It is used to transform DRM protected files

when they arrive on a device into a compatible format for storing it securely

on the device. It is also used to intercept content and ensure it is stored

in an agent's private directory. </p> <p><b>Consumer API </b> </p> <p>The

classes <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-FC40011B-32D3-328B-BB59-35BEF46A215A"><apiname>ContentAccess::CContent</apiname></xref> and <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-B54C8391-FE69-324C-AC0A-1E88C2555F00"><apiname>ContentAccess::CData</apiname></xref> together

represents the consumer API. </p> <p>The consumer API allows applications

to view the content as plain text, regardless of how it is actually stored

on the device. (For instance, it might be encrypted). It is used by applications

to render content and multimedia plug-ins. <b>Note</b>: Rendering implies

reading data from a file, transforming it, then playing or displaying it on

the device. </p> <p><b>Manager API </b> </p> <p>The <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-671191B1-B249-3DD3-A5E8-6F1A41A371C8"><apiname>ContentAccess::CManager</apiname></xref> class,

which manages the files and content access agents forms the manager API. </p> <p><b>Rights

Manager API </b> </p> <p>The <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-2CBEF3AA-7101-3247-BAED-79B624CEBBD1"><apiname>ContentAccess::CRightsManager</apiname></xref> class,

which manages DRM rights within a particular DRM agent forms the rights manager

API. </p> <p><b>Agent API </b> </p> <p>The <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-798F4B18-D6AE-36B9-B03F-C1FC55266CB5"><apiname>ContentAccess::CAgentFactory</apiname></xref> class

forms the agent interface. It allows to integrate new agents at a later date,

dynamically if required. The agent's factory produces products derived from

the following: </p> <ul>

<li id="GUID-72BCBDF7-5352-5907-902F-42CAB9C9BF55"><p> <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-983AF0B0-F0FD-31C6-94DF-C695A5D2B2D0"><apiname>ContentAccess::CAgentContent</apiname></xref>  </p> </li>

<li id="GUID-35289C35-01FA-52A5-8AFF-BBF3F870AA87"><p> <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-D9B55B22-9A2D-3475-80CB-37D44E11F34B"><apiname>ContentAccess::CAgentData</apiname></xref>  </p> </li>

<li id="GUID-4CF57B3A-8D8F-5B03-9E4A-A0A12A71FF53"><p> <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-89000D71-032A-3F08-947C-AF7006A06D2F"><apiname>ContentAccess::CAgentImportFile</apiname></xref>  </p> </li>

<li id="GUID-B7CA6E3F-59CA-5CA1-A65B-E055B5ECCC8B"><p> <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-D7457871-5361-3684-9A95-FBDB9C2689DD"><apiname>ContentAccess::CAgentManager</apiname></xref>  </p> </li>

<li id="GUID-871A9A11-7705-50DC-B528-8357FCD1A997"><p> <xref href="GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601.dita#GUID-0F5CE9B5-E674-3962-8376-CFB1ECB2F601/GUID-441831EC-2FC0-340E-B276-BFFA00665FD2"><apiname>ContentAccess::CAgentRightsManager</apiname></xref>  </p> </li>

</ul> </section>

<section><title>Typical uses</title> <p>CAF provides interfaces for implementing

and using CAF agents. CAF agents allows authorised users to access the DRM

protected content for installation and playback. CAF APIs can be used to perform

the following tasks: </p> <ul>

<li id="GUID-02285849-C4FA-58AC-BFE1-0D77A9A5FF51"><p>Handling delivery and

transformation of DRM protected content. For more information, see <xref href="GUID-1B20D403-5FC9-5A61-9D2B-8ACB9D73423C.dita">Supplier

API Tutorial</xref>. </p> </li>

<li id="GUID-E039C0ED-5A67-5326-8431-047985855B23"><p>Providing services for

applications that render content and multimedia plug-ins. For more information,

see <xref href="GUID-09A760FD-4C2A-5F79-91F2-DCC25A63699C.dita">Consumer API Tutorial</xref>. </p> </li>

<li id="GUID-769084EB-0B7A-514B-9453-9277DBD9D4E1"><p>Managing files and CAF

agents. For more information, see <xref href="GUID-920CF819-645B-5705-8017-C1FAD7C6ABAF.dita">Manager

API Tutorials</xref>. </p> </li>

<li id="GUID-E8EF07A8-4348-5F42-918C-F2BE7877EF31"><p>Managing DRM rights

within a particular DRM agent. For more information, see <xref href="GUID-77578F7E-E6E0-5177-99B2-E586DD6DD0C6.dita">Rights

Manager API Tutorial</xref>. </p> </li>

</ul> </section>

</conbody><related-links>

<link href="GUID-986EBD34-DE90-59BA-8A5F-E6E48845F18E.dita"><linktext>CAF Recogniser

Config</linktext></link>

<link href="GUID-AD61E913-9720-5F6B-8386-680384165E87.dita"><linktext>CAF Streaming

Support</linktext></link>