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 Apparc framework uses data type recognizers derived from \c CApaDataRecognizerType 
sl@0: // to determine the MIME type of files in Symbian OS. Apparc supplies the filename and 
sl@0: // a buffer containing bytes read from the start of the file. If a file is recognized, 
sl@0: // the recognizer must return the MIME type and the degree of confidence in recognizing 
sl@0: // the file (a \c TInt ranging from <code>"KMinInt=Not Recognized"</code> to <code>"KMaxInt=Certain"</code>).
sl@0: // The implementation of DRM presents a problem when determinining the MIME type. Usually, a DRM 
sl@0: // file stores one or more content objects. For example, an OMA file with 
sl@0: // MIME type <code>application/vnd.oma.drm.content</code> might store an image file with 
sl@0: // MIME type <code>image/jpeg</code>. Apparc expects only one MIME type to be returned, not two. 
sl@0: // The CAF recognizer <code>RECCAF.DLL</code> uses the 
sl@0: // to determine whether or not a file is recognized by the content access framework and 
sl@0: // if so retrieves these two MIME types.
sl@0: // The mapping of these two MIME types returned by CAF to a single MIME type follows these rules:
sl@0: // <table border=1>
sl@0: // <tr><th> File MIME Type </th><th> Content MIME Type              </th><th> Apparc MIME Type                         </th></tr>
sl@0: // <tr><td> Present        </td><td> Present                        </td><td> <code><i>x-caf-</i>ContentMimeType</code></td></tr>
sl@0: // <tr><td> Present        </td><td> Not Present                    </td><td> <code>FileMimeType</code>                </td></tr>
sl@0: // <tr><td> Present        </td><td> <code>application/x-caf</code> </td><td> <code>application/x-caf</code>           </td></tr>
sl@0: // </table>
sl@0: // The rationale for the above mapping is as follows:
sl@0: // Access Framework. A file is either recognized by an agent or it is not recognized.
sl@0: // <hr>
sl@0: // When recognizing a file, Apparc supplies the name of the file to be recognized, and a 
sl@0: // buffer containing the start of the file, to all <code>CApaDataRecognizerType::DoRecognizeL()</code> 
sl@0: // implementations. These two parameters can be passed to the <code>ContentAccess::CAgentResolver::DoRecognize()</code> 
sl@0: // function to determine whether one of the Content Access Agents recognizes the file. 
sl@0: // CApaDataRecognizer::DoRecognize(TDesC& aFilename, TDesC8& aBuffer)
sl@0: // TBool recognized;
sl@0: // CAgentResolver *resolver = CAgentResolver::NewL();
sl@0: // recognized = resolver->DoRecognize(filename, buffer, fileMimeType, contentMimeType);
sl@0: // <code>ContentAccess::CAgentResolver::DoRecognize()</code> passes the filename and buffer to each of the  
sl@0: // agents in turn. The agents perform the recognition, and the result is returned 
sl@0: // as either \c ETrue if the file was recognized, or \c EFalse if it was not. If the file 
sl@0: // is recognized, the \c fileMimeType and \c contentMimeType parameters are populated 
sl@0: // with the correct MIME types.
sl@0: // The recognition is distributed to the agents because they are able to recognize 
sl@0: // a file belonging to their agent. They are also able to examine the contents to 
sl@0: // work out the content MIME type. This allows one generic CAF recognizer to be used 
sl@0: // for all the agents implemented with the content access framework.
sl@0: // <hr>
sl@0: // The following diagram illustrates the recognition of an OMA file with 
sl@0: // JPEG content.
sl@0: // <hr>
sl@0: // The CAF recognizer configuration file is stored in the Apparc server's
sl@0: // private directory \c \\private\\10003a3f\\RecCaf\\RecCafMimeTypes.txt.
sl@0: // It is just a list of all known content MIME types. The list allows the 
sl@0: // recognizer to return a fixed set of MIME types when 
sl@0: // Apparc calls the recognizer's <code>CApaCafRecognizer::SupportedDataTypeL()</code> fuction.
sl@0: // image/jpeg
sl@0: // image/gif
sl@0: // text/plain
sl@0: // text/html
sl@0: // ... etc
sl@0: // If this file is replaced (to support new content types), the recognizer 
sl@0: // will only implement the changes during the next power on. Similarly if a new agent 
sl@0: // is added, the recognizer will only rebuild its list of agents after the next power on.
sl@0: // <hr>
sl@0: // In order to use CAF content, applications will need to update their registration resource files (e.g. 
sl@0: // <code>AppName_reg.rss</code>) to include the new CAF MIME types. For example, in the past an image 
sl@0: // viewer may have only included <code>image/jpeg</code> in the list of MIME types it could open. 
sl@0: // If the application is updated to use the Content Access Framework, it should support 
sl@0: // <code>image/jpeg</code> and <code>x-caf-image/jpeg</code> in order to support 
sl@0: // unprotected and protected content respectively. See the registration file examples below.
sl@0: // All file operations should be conducted through the CAF framework, so that the 
sl@0: // application will not need to know anything about a specific DRM scheme.
sl@0: // <b>Registration file that doesn't use CAF</b>
sl@0: // datatype_list = 
sl@0: // DATATYPE { priority= EDataTypePriorityHigh ; type="image/jpeg"; },
sl@0: // <b>Registration file that does use CAF</b>
sl@0: // datatype_list = 
sl@0: // DATATYPE { priority= EDataTypePriorityHigh ; type="image/jpeg"; },
sl@0: // DATATYPE { priority= EDataTypePriorityHigh ; type="x-caf-image/jpeg"; },
sl@0: // <hr>
sl@0: // 
sl@0: //
sl@0: 
sl@0: /**
sl@0:  @page CAFRecognizer How to write an Apparc recognizer for the Content Access Framework
sl@0:  - @ref RecognizerOverview
sl@0:  - @ref DoRecognize
sl@0:  - @ref ConfigFile
sl@0:  - @ref AppRegFiles
sl@0:  @section RecognizerOverview Overview 
sl@0:  <code>ContentAccess::CAgentResolver::DoRecognize()</code> function @ref DoRecognize "(see below)"  
sl@0:  @li Users and applications will be interested in the MIME type of the content within a file not the packaging. CAF abstracts the packaging.
sl@0:  @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
sl@0:  @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
sl@0:  @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.
sl@0:  @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.
sl@0:  @note The concept of "confidence" has also been eliminated for the files within the Content 
sl@0:  @section DoRecognize How to determine the file and content MIME types of a DRM file
sl@0:  @code
sl@0:  @endcode
sl@0:  @image html recognizer.gif
sl@0:  @section ConfigFile CAF Recognizer Configuration File
sl@0:  @code
sl@0:  @endcode
sl@0:  @section AppRegFiles Application Registration files
sl@0:  @code
sl@0:  @endcode	
sl@0:  @code
sl@0:  @endcode	
sl@0: */