1 // Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).

     2 // All rights reserved.

     3 // This component and the accompanying materials are made available

     4 // under the terms of the License "Symbian Foundation License v1.0"

     5 // which accompanies this distribution, and is available

     6 // at the URL "http://www.symbianfoundation.org/legal/sfl-v10.html".

     7 //

     8 // Initial Contributors:

     9 // Nokia Corporation - initial contribution.

    10 //

    11 // Contributors:

    12 //

    13 // Description:

    14 // <hr>

    15 // The Apparc framework uses data type recognizers derived from \c CApaDataRecognizerType 

    16 // to determine the MIME type of files in Symbian OS. Apparc supplies the filename and 

    17 // a buffer containing bytes read from the start of the file. If a file is recognized, 

    18 // the recognizer must return the MIME type and the degree of confidence in recognizing 

    19 // the file (a \c TInt ranging from <code>"KMinInt=Not Recognized"</code> to <code>"KMaxInt=Certain"</code>).

    20 // The implementation of DRM presents a problem when determinining the MIME type. Usually, a DRM 

    21 // file stores one or more content objects. For example, an OMA file with 

    22 // MIME type <code>application/vnd.oma.drm.content</code> might store an image file with 

    23 // MIME type <code>image/jpeg</code>. Apparc expects only one MIME type to be returned, not two. 

    24 // The CAF recognizer <code>RECCAF.DLL</code> uses the 

    25 // to determine whether or not a file is recognized by the content access framework and 

    26 // if so retrieves these two MIME types.

    27 // The mapping of these two MIME types returned by CAF to a single MIME type follows these rules:

    28 // <table border=1>

    29 // <tr><th> File MIME Type </th><th> Content MIME Type              </th><th> Apparc MIME Type                         </th></tr>

    30 // <tr><td> Present        </td><td> Present                        </td><td> <code><i>x-caf-</i>ContentMimeType</code></td></tr>

    31 // <tr><td> Present        </td><td> Not Present                    </td><td> <code>FileMimeType</code>                </td></tr>

    32 // <tr><td> Present        </td><td> <code>application/x-caf</code> </td><td> <code>application/x-caf</code>           </td></tr>

    33 // </table>

    34 // The rationale for the above mapping is as follows:

    35 // Access Framework. A file is either recognized by an agent or it is not recognized.

    36 // <hr>

    37 // When recognizing a file, Apparc supplies the name of the file to be recognized, and a 

    38 // buffer containing the start of the file, to all <code>CApaDataRecognizerType::DoRecognizeL()</code> 

    39 // implementations. These two parameters can be passed to the <code>ContentAccess::CAgentResolver::DoRecognize()</code> 

    40 // function to determine whether one of the Content Access Agents recognizes the file. 

    41 // CApaDataRecognizer::DoRecognize(TDesC& aFilename, TDesC8& aBuffer)

    42 // TBool recognized;

    43 // CAgentResolver *resolver = CAgentResolver::NewL();

    44 // recognized = resolver->DoRecognize(filename, buffer, fileMimeType, contentMimeType);

    45 // <code>ContentAccess::CAgentResolver::DoRecognize()</code> passes the filename and buffer to each of the  

    46 // agents in turn. The agents perform the recognition, and the result is returned 

    47 // as either \c ETrue if the file was recognized, or \c EFalse if it was not. If the file 

    48 // is recognized, the \c fileMimeType and \c contentMimeType parameters are populated 

    49 // with the correct MIME types.

    50 // The recognition is distributed to the agents because they are able to recognize 

    51 // a file belonging to their agent. They are also able to examine the contents to 

    52 // work out the content MIME type. This allows one generic CAF recognizer to be used 

    53 // for all the agents implemented with the content access framework.

    54 // <hr>

    55 // The following diagram illustrates the recognition of an OMA file with 

    56 // JPEG content.

    57 // <hr>

    58 // The CAF recognizer configuration file is stored in the Apparc server's

    59 // private directory \c \\private\\10003a3f\\RecCaf\\RecCafMimeTypes.txt.

    60 // It is just a list of all known content MIME types. The list allows the 

    61 // recognizer to return a fixed set of MIME types when 

    62 // Apparc calls the recognizer's <code>CApaCafRecognizer::SupportedDataTypeL()</code> fuction.

    63 // image/jpeg

    64 // image/gif

    65 // text/plain

    66 // text/html

    67 // ... etc

    68 // If this file is replaced (to support new content types), the recognizer 

    69 // will only implement the changes during the next power on. Similarly if a new agent 

    70 // is added, the recognizer will only rebuild its list of agents after the next power on.

    71 // <hr>

    72 // In order to use CAF content, applications will need to update their registration resource files (e.g. 

    73 // <code>AppName_reg.rss</code>) to include the new CAF MIME types. For example, in the past an image 

    74 // viewer may have only included <code>image/jpeg</code> in the list of MIME types it could open. 

    75 // If the application is updated to use the Content Access Framework, it should support 

    76 // <code>image/jpeg</code> and <code>x-caf-image/jpeg</code> in order to support 

    77 // unprotected and protected content respectively. See the registration file examples below.

    78 // All file operations should be conducted through the CAF framework, so that the 

    79 // application will not need to know anything about a specific DRM scheme.

    80 // <b>Registration file that doesn't use CAF</b>

    81 // datatype_list = 

    82 // DATATYPE { priority= EDataTypePriorityHigh ; type="image/jpeg"; },

    83 // <b>Registration file that does use CAF</b>

    84 // datatype_list = 

    85 // DATATYPE { priority= EDataTypePriorityHigh ; type="image/jpeg"; },

    86 // DATATYPE { priority= EDataTypePriorityHigh ; type="x-caf-image/jpeg"; },

    87 // <hr>

    88 // 

    89 //

    90 

    91 

    92 

    93 /**

    94  @page CAFRecognizer How to write an Apparc recognizer for the Content Access Framework

    95  - @ref RecognizerOverview

    96  - @ref DoRecognize

    97  - @ref ConfigFile

    98  - @ref AppRegFiles

    99  @section RecognizerOverview Overview 

   100  <code>ContentAccess::CAgentResolver::DoRecognize()</code> function @ref DoRecognize "(see below)"  

   101  @li Users and applications will be interested in the MIME type of the content within a file not the packaging. CAF abstracts the packaging.

   102  @li If the content is recognized with only the MIME type of the content within the file, it would confuse legacy applications who thought the entire file was that MIME type

   103  @li Prefixing the content type with <code>"x-caf-"</code> shows it is a file that can be opened by CAF to read that content type without confusing legacy applications

   104  @li A file that needs to be passed through the supplier interface before it can be used will just be recognized as the file MIME type, the content type is irrelevant before the supply operation.

   105  @li A file containing many content objects should just be recognized as <code>application/x-caf</code> since the packaging of the archive is irrelevant. CAF abstracts the packaging.

   106  @note The concept of "confidence" has also been eliminated for the files within the Content 

   107  @section DoRecognize How to determine the file and content MIME types of a DRM file

   108  @code

   109  @endcode

   110  @image html recognizer.gif

   111  @section ConfigFile CAF Recognizer Configuration File

   112  @code

   113  @endcode

   114  @section AppRegFiles Application Registration files

   115  @code

   116  @endcode	

   117  @code

   118  @endcode	

   119 */