View source

{{KBTS}}
__NOTOC__ 
__NOEDITSECTION__

[[Category:Technical Solution]]

{{KnowledgeBase
|id=TSS000419
|platform=S60 3rd Edition
|devices=
|category=Symbian C<nowiki>++</nowiki>
|subcategory=General<br>Application Framework
|creationdate=September 21, 2006
|keywords=
}}

== Overview ==
S60 MIME recognizers and opening files for editing

== Description ==
It is a common requirement that developers would want to launch their custom file editors and viewers automatically when the "OK" key is pressed in the file browser. It is possible to achieve this using S60 file type recognizers. This solution describes how to write such a plug-in and also how to view and/or edit a file that has been opened.<br>'''Writing a recognizer'''<br>Recognizers on S60 3rd Edition need to provide a standard ECOM factory code to create an instance of the recognizer. All data recognizers must implement the polymorphic interface defined by CApaDataRecognizerType.<br>The pure virtual function SupportedDataTypeL() must be implemented. It returns the MIME type(s) that the recognizer is capable of recognizing.<br>For example, the code snippet can be as follows in your recognizer :<br>_LIT8(KExampleTextMimeType, "text/example");<br>TDataType CExampleRecognizer::SupportedDataTypeL(TInt /*aIndex*/) const<br>&nbsp;&nbsp;&nbsp;&nbsp;<nowiki>{</nowiki><br>&nbsp;&nbsp;&nbsp;&nbsp;return TDataType(KExampleTextMimeType);<br>&nbsp;&nbsp;&nbsp;&nbsp;<nowiki>}</nowiki><br>All recognizers must implement also the DoRecognizeL() function that is called to do the data recognition. Implementations should set iDataType to the MIME type it considers the data to belong to and iConfidence to indicate a confidence rating for the recognition process.<br>The function can look like this in the recognizer :<br>void CExampleRecognizer::DoRecognizeL(const TDesC& aName, const TDesC8& aBuffer)<br>&nbsp;&nbsp;&nbsp;&nbsp;<nowiki>{</nowiki><br>&nbsp;&nbsp;&nbsp;&nbsp;_LIT8(KExampleData, "example");<br>&nbsp;&nbsp;&nbsp;&nbsp;_LIT(KDotExample, ".Example");<br>&nbsp;&nbsp;&nbsp;&nbsp;TParse parse;<br>&nbsp;&nbsp;&nbsp;&nbsp;parse.Set(aName,NULL,NULL);<br>&nbsp;&nbsp;&nbsp;&nbsp;// extract the extension from the filename<br>&nbsp;&nbsp;&nbsp;&nbsp;TPtrC ext=parse.Ext();<br>&nbsp;&nbsp;&nbsp;&nbsp;if (ext.CompareF(KDotExample) == 0 &&<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;aBuffer.FindF(KExampleData)!= KErrNotFound)<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<nowiki>{</nowiki><br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;iConfidence = ECertain;<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;iDataType = TDataType(KExampleTextMimeType);<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<nowiki>}</nowiki><br>&nbsp;&nbsp;&nbsp;&nbsp;<nowiki>}</nowiki><br>The process of creating a recognizer is the same in S60 2nd Edition except that ECOM plugin framework is not used. In S60 2nd Edition, the recognizers are DLLs having .MDL extension and UID2 value of 0x10003A19. MDL recognizers are stored in the \system\recogs folder.<br>'''Registering for a MIME type'''<br>When developing an application to handle a particular MIME type, the application has to register itself giving the MIME type that it can handle. This is done in the client application<nowiki>’</nowiki>s _reg.rss file.<br>The datatype_list section of the registration file lists the MIME types that the application supports, and the priority of support that each type is given. When a file is to be opened, Symbian OS launches the application that has the highest priority support for the data type.<br>An example of the file (Applications _reg.rss) is given below:<br><nowiki>#</nowiki>include "Helloworldbasic.loc"<br><nowiki>#</nowiki>include <nowiki><</nowiki>appinfo.rh<nowiki>></nowiki><br><nowiki>#</nowiki>include <nowiki><</nowiki>Helloworldbasic.rsg<nowiki>></nowiki><br>UID2 KUidAppRegistrationResourceFile<br>UID3 0x10005B91<br>RESOURCE APP_REGISTRATION_INFO<br>&nbsp;&nbsp;<nowiki>{</nowiki><br>&nbsp;&nbsp;app_file="HelloWorldBasic";<br>&nbsp;&nbsp;localisable_resource_file =<br>&nbsp;&nbsp;&nbsp;&nbsp;qtn_helloworldbasic_loc_resource_file_1;<br>&nbsp;&nbsp;localisable_resource_id =<br>&nbsp;&nbsp;&nbsp;&nbsp;R_HELLOWORLDBASIC_LOCALISABLE_APP_INFO;<br>&nbsp;&nbsp;embeddability = KAppEmbeddable;<br>&nbsp;&nbsp;datatype_list =<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<nowiki>{</nowiki><br>&nbsp;'''&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;DATATYPE'''<br>'''&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<nowiki>{</nowiki>'''<br>'''&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;priority=EDataTypePriorityHigh;'''<br>'''&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;type="text/plain";'''<br>'''&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<nowiki>}</nowiki>'''<br>'''&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<nowiki>}</nowiki>;'''<br>&nbsp;&nbsp;<nowiki>}</nowiki><br>'''Passing file handle to viewer/editor'''<br>When a file is called by a system application like File Manager or Messaging App, the following function of the handler application is called:<br>CAknDocument::OpenFileL(<br>&nbsp;&nbsp;&nbsp;&nbsp;CFileStore*& aFileStore,<br>&nbsp;&nbsp;&nbsp;&nbsp;RFile& aFile)<br>where aFile is opened in read mode. So it<nowiki>’</nowiki>s not possible for the client<nowiki>’</nowiki>s application to make changes to the file directly. The solution for this is to open a new temporary file with the content of the file, edit the temporary file, and replace it with the original file.<br>Another way of doing this is to extract the filename and delegate the processing to a separate engine or the AppUi class:<br>void CHelloWorldBasicDocument::OpenFileL(<br>&nbsp;&nbsp;CFileStore*& aFileStore,RFile& aFile)<br>&nbsp;&nbsp;<nowiki>{</nowiki><br>&nbsp;&nbsp;aFileStore=NULL;<br>&nbsp;&nbsp;TFileName iFileName;<br>&nbsp;&nbsp;aFile.FullName(iFileName);<br>&nbsp;&nbsp;Process()-<nowiki>></nowiki>SetMainDocFileName(iFileName);<br>&nbsp;&nbsp;TUint fileMode = EFileWrite<nowiki>|</nowiki>EFileShareExclusive;<br>&nbsp;&nbsp;SetAppFileMode(fileMode);<br>&nbsp;&nbsp;aFile.Close();<br>&nbsp;&nbsp;iAppUi-<nowiki>></nowiki>LoadFile(iFileName);<br>&nbsp;&nbsp;// File processing could be also delegated to<br>&nbsp;&nbsp;// a separate engine or a view.<br>&nbsp;&nbsp;<nowiki>}</nowiki><br>The difference between S60 2nd Edition and S60 3rd Edition is that in S60 2nd Edition,<br>&nbsp;CAknDocument::OpenFileL(<br>&nbsp;&nbsp;&nbsp;&nbsp;TBool aDoOpen, const TDesc& aFileName, RFs& aFs)<br>gets called with the file name instead of handle. So, the problem with an already-opened file handle does not occur in S60 2nd Edition.<br>When the file that is being opened is in a private folder or there is no need to open it in write mode, then a duplicate of the file handle can be maintained for future use.<br>'''Opening a file in write mode'''
* Create a temporary file with the same contents as that of the original file. The contents can be extracted by using the RFs and RFile APIs and can be copied into the temporary file.
* Make the changes by either manipulating the temp. file directly or launching one<nowiki>’</nowiki>s own view (similar to an editor).
* When saving, delete the original file and rename the temporary file with the original filename.<br>BaflUtils::DeleteFile(iFsSession, iOriginalFile);<br>BaflUtils::RenameFile(iFsSession,iTempFile,iOriginalFile);<br>'''Common problems:'''<br>One of the most common errors that one gets while trying to open a file in write mode while running in embedded mode is KErrInUse(-14).<br>This occurs because the Document Handler Framework opens the file in shareable read mode and shares the session with the application. Therefore, it<nowiki>’</nowiki>s not possible for the application to open the file in write mode. In order to delete the original file and rename the temporary file, the handler application must wait for the OpenFileL() to return. &nbsp;It<nowiki>’</nowiki>s not possible to delete or manipulate the file within OpenFileL(). 

[[Category:Symbian C++]][[Category:S60 3rd Edition]]