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

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

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

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

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

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

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

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

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

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

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

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

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

    23 content </p> </li>

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

    25 information </p> </li>

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

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

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

    29 DRM schemes </p> </li>

    30 </ul> </section>

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

    32 and terms</title> <dl>

    33 <dlentry>

    34 <dt>Content</dt>

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

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

    37 </dlentry>

    38 </dl> <dl>

    39 <dlentry>

    40 <dt>Content consumer</dt>

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

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

    43 </dlentry>

    44 </dl> <dl>

    45 <dlentry>

    46 <dt>Content access agent</dt>

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

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

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

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

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

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

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

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

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

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

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

    58 policy. </p> </li>

    59 </ul> </dd>

    60 </dlentry>

    61 </dl> <dl>

    62 <dlentry>

    63 <dt>F32 agent</dt>

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

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

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

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

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

    69 </dlentry>

    70 </dl> <dl>

    71 <dlentry>

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

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

    74 They can share their files existence to applications through implementation

    75 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.

    76 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

    77 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

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

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

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

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

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

    83 </dlentry>

    84 </dl> </section>

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    99 components provided by Symbian and the blue blocks represent the components

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

   101 <title>              CAF Architecture            </title>

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

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

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

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

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

   107 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">

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

   109 <thead>

   110 <row>

   111 <entry>Class</entry>

   112 <entry>Description</entry>

   113 </row>

   114 </thead>

   115 <tbody>

   116 <row>

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

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

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

   120 </row>

   121 <row>

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

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

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

   125 </row>

   126 <row>

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

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

   129 </row>

   130 <row>

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

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

   133 </row>

   134 <row>

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

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

   137 </row>

   138 <row>

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

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

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

   142 </row>

   143 </tbody>

   144 </tgroup>

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

   146 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

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

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

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

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

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

   152 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

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

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

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

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

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

   158 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,

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

   160 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,

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

   162 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

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

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

   165 the following: </p> <ul>

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

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

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

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

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

   171 </ul> </section>

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

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

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

   175 the following tasks: </p> <ul>

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

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

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

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

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

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

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

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

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

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

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

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

   188 </ul> </section>

   189 </conbody><related-links>

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

   191 Config</linktext></link>

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

   193 Support</linktext></link>

   194 </related-links></concept>