CS001051 - Creating a handler application for a MIME type

From Forum Nokia Wiki

ID	CS001051	Creation date	July 1, 2008
Platform	S60 3rd Edition, MR	Tested on devices	Nokia N95 8GB
Category	Symbian C++	Subcategory	Files/Data

Keywords (APIs, classes, methods, functions): CAknDocument, CAknDocument::OpenFileL()

Overview

It is sometimes necessary to launch a handler application (such as a viewer) for files selected, for example, through the File manager. This code snippet demonstrates how to write a handler for TeX files (MIME type: application/x-tex).

Note: If the MIME type of the file is not known, the handler application cannot be launched. In this case, you need to write a data recognizer that identifies the MIME type of the file. For more information about implementing a data recognizer, see CS001050 - Creating a recognizer plug-in for a MIME type.

Resource file: CTeXHandler_reg.rss

The data handler is registered to handle that particular MIME type by adding a datatype_list section to the application's reg.rss file. The section lists the MIME types that the application is able to handle, and the priority of support for each MIME type. The priority can be one of the following four values:

EDataTypePriorityHigh
EDataTypePriorityNormal
EDataTypePriorityLow
EDataTypePriorityLastResort

Symbian OS launches the application that has the highest priority support for the data type in question.

Here is the relevant part of the reg.rss file:

RESOURCE APP_REGISTRATION_INFO
    {
    app_file = "CTeXHandler";
    localisable_resource_file = qtn_loc_resource_file;
    localisable_resource_id = R_LOCALISABLE_APP_INFO;
 
    embeddability = KAppEmbeddable;
    datatype_list = 
        {
        DATATYPE
            {
            priority = EDataTypePriorityHigh;
            type = "application/x-tex";
            }
        };
    }

Header file: CTeXHandlerDocument.h

#include <akndoc.h>  // CAknDocument
 
class CTeXHandlerDocument : public CAknDocument
    {
    // ...
 
    public: // Functions from base classes
        /**
         * From CAknDocument.
         * Create a CTeXHandlerAppUI object and return a pointer to it.
         * The object returned is owned by the Uikon framework.
         * @return a pointer to the created instance of AppUI.
         */
        CEikAppUi* CreateAppUiL();
 
        /**
         * From CAknDocument.
         * Opens a file. 
         */
        void OpenFileL(CFileStore*& aFileStore, RFile& aFile);
 
    private:  // Data
        CEikAppUi* iAppUI;
    };

Source file: CTeXHandlerDocument.cpp

CEikAppUi* CTeXHandlerDocument::CreateAppUiL()
    {
    // Create the application user interface, and return a pointer to it;
    // the framework takes ownership of this object
    iAppUI = new (ELeave) CTeXHandlerAppUI();
    return iAppUI;
    }
 
void CTeXHandlerDocument::OpenFileL(CFileStore*& aFileStore, RFile& aFile)
    {
    // Store the filename in a local variable
    TFileName filename;
    aFile.Name(filename);
 
    // Store the first few characters of the file contents in a local variable
    const TInt KCharsToRead = 20;
    TBuf8<KCharsToRead> contents;
    User::LeaveIfError(aFile.Read(contents, KCharsToRead));
 
    // Delegate file handling to the application UI
    CTeXHandlerAppUI *appUI = static_cast<CTeXHandlerAppUI*>(iAppUI);
    appUI->SetFileData(filename, contents);
    }

Header file: CTeXHandlerAppUI.h

#include <aknappui.h>
 
class CTeXHandlerAppUI : public CAknAppUi
    {
    // ...
 
    public:  // New functions
        /**
         * Handles the file.
         */
        void SetFileData(TDes& aFileName, TDes8& aData);
 
    private: // Data
        /**
         * The application view.
         * Owned by CTeXHandlerAppUI.
         */
        CTeXHandlerAppView* iAppView;
    };

Source file: CTeXHandlerAppUI.cpp

void CTeXHandlerAppUI::SetFileData(TDes& aFileName, TDes8& aData)
    {
    if (iAppView)
        {
        iAppView->SetFileData(aFileName, aData);
        }
    }

Header file: CTeXHandlerAppView.h

#include <coecntrl.h>
 
class CTeXHandlerAppView : public CCoeControl
    {
    // ...
 
    public:  // New functions
        /**
         * Handles the file.
         */
        void SetFileData(TDes& aFileName, TDes8& aData);
 
    // ...
    };

Source file: CTeXHandlerAppView.cpp

void CTeXHandlerAppView::SetFileData(TDes& aFileName, TDes8& aData)
    {
    // Handle the TeX file: Draw its contents onto the screen etc.
    }

Postconditions

A handler for TeX files is implemented. If the file of type application/x-tex is opened for example from the File manager, the CTeXHandlerDocument::OpenFileL() method is called. It delegates file handling to the view object: CTeXHandlerAppView::SetFileData().

Community: Wiki