S60 Platform: Document Handler Example

-------------------------------------------------

 

This C++ example demonstrates how to use the Document Handler and the Recognizer

to open and handle certain file types.

 

In the file opening process, if the MIME type of the file is recognized, a handler

application (registered to handle that specific MIME type) is opened and the file

is given to that application.

 

Recognizers are used for handling certain file types. The files are recognized,

for example, using their extensions. Recognizers are implemented as ECom plugins

in S60 3rd Edition. When there is an attempt to open a file, the recognizer plugins

are gone through and asked if they recognize the file.

 

Note that a developer certificate is needed for the recognizer due to its ProtServ

capability requirement.

 

The Document Handler example consists of three components:

-TestApp tries to open a file with a specific MIME type (".new" extension)

-RecognizerDll recognizes the extension

-HandlerApp is launched to open the file

 

--------------------------------------------------------------------------------

 

PREREQUISITES

 

Symbian C++ basics

 

--------------------------------------------------------------------------------

 

IMPORTANT FILES/CLASSES

 

Tester application:

-------------------

 

The CDocumentHandler is used in the tester application’s CTestAppAppUi::LaunchFileL

function. The same class has a RefreshDocumentFileL function which

updates the open file if the application is running.

 

Recognizer:

-----------

Recognizers are implemented by inheriting CApaDataRecognizerType as follows:

class CApaExRecognizer : public CApaDataRecognizerType

 

The important functions are:

* DoRecognizeL

    - Does the actual recognition. If the recognizer recognizes the

      file, its iConfidence member is set to

      TRecognitionConfidence::ECertain.

                

* CreateRecognizerL

    - Static factory function which creates the recognizer object.

 

* SupportedDataTypeL

     - Returns the MIME type of the file when it is recognized.

       IMPORTANT: The MIME type is used when launching the handler application.

       The handler application's registry file contains a datatype list

       which declares that it can be used to handle the MIME type.

       "application/something-totally-new"

 

        datatype_list =

            {

            DATATYPE

                {

                priority = EDataTypePriorityHigh;

                type = "application/something-totally-new";

                }

            };       

 

       In S60 1st and 2nd Edition the datatype_list declaration is in the AIF resource file.

      

       Once the application is launched, the document class’s

       OpenFileL(CFileStore*& aFileStore, RFile& aFile)

       function is called.

 

       The example application reads the file name and the beginning of the

       file. These values are shown in the view.

 

Handler application:

-------------------

The handler application receives notifications of the file in the CHandlerDocument::OpenFileL

function. The overloaded version

void CHandlerDocument::OpenFileL(CFileStore*& aFileStore, RFile& aFile)

is used in S60 3rd Edition and

CFileStore* OpenFileL( TBool aDoOpen, const TDesC& aFilename, RFs& aFs )

in S60 1st and 2nd Editions.

 

In order for the latter to work, the

ProcessCommandParametersL(TApaCommand ,TFileName& ,const TDesC8& )

function in the AppUi class has to return ETrue; otherwise the

OpenFileL function is never called.

 

The CHandlerAppUi::OpenFileL(const TDesC& aFileName) receives the new file name

when the handler is already running.

 

If the handler application is already running, the OpenFileL method does not get

any notification of the switched file; it is just brought to foreground. Because of

this, a special technique is used to update the file. CDocumentHandler provides a

HandlerAppUid function (introduced in S60 2nd Edition, FP3) which returns the UID

of the handler application. The task is searched using the UID

(see CTestAppAppUi::RefreshDocumentFileL). If the task is found, it means that it

is already running. Then its open file is updated by calling TApaTask::SwitchOpenFile.

The handler application receives a notification to the CHandlerAppUi::OpenFileL function

and the file is switched.

 

In S60 releases before S60 2nd Edition, FP3, use RApaLsSession class's AppForDocument

function instead for updating the file.

 

 

 

Important classes:

CDocumentHandler, CApaDataRecognizerType

 

--------------------------------------------------------------------------------

 

KNOWN ISSUES

 

   

--------------------------------------------------------------------------------

 

RUNNING THE EXAMPLE

 

 

The example contains two GUI applications: the hander application (HandlerApp)

and the tester application (TesterApp).

 

Start the tester application. It has two options, "Test" and "Test Embedded" to

launch the the handler application as a standalone application and in embedded mode,

respectively.

 

The example includes a tester application, which launches one of the two test files

(test.new and test2.new). The test files are installed to the phone

(in ..\Images\Pictures directory in c:\\drive) and exported to the SDK, so the example

can be used right away.

 

You can also test the handler application by creating a file with the extension ".new"

and then opening the file. The handler application should be launched.

 

Once the Handler application is launched, it shows the file name and

the beginning of the file.

 

--------------------------------------------------------------------------------

 

BUILD & INSTALLATION INSTRUCTIONS

 

Steps for building and installing the application to a device depend on the S60 platform version.

The following instructions explain building from a common group directory, but it is also possible

to build the RecognizerDll, HandlerApp, and TestApp separately from their own group directories.

 

--Mobile device (S60 3rd Edition)

    cd to /group

    bldmake bldfiles

    abld build gcce urel

 

    cd to /RecognizerDll/sis

    Edit the RecognizerEx.pkg's paths to match those on your system.

    makesis RecognizerEx.pkg

 

   Create .sis files to HandlerApp and TestApp similarly in /HandlerApp/sis and

   /TestApp/sis directories.

 

 

    Sign the SIS packages:

 

    - The recognizer SIS file has to be signed using a developer certificate

      due to its requirement for ProtServ capability. The developer certificate can

      be obtained from www.symbiansigned.com.

 

    - The HandlerApp and TestApp can be self-signed (the application UID has to be changed to the

      unprotected range). See the SDK Help for information about self-signed .sis packages, or

      www.symbiansigned.com for information about Developer Certificates.

 

    Install the signed .sis files to an S60 3rd Edition device.   

 

    If you get a "Certificate error" during installation of a self-signed

    package, check that App.Manager -> Settings -> Software Installation is

    set to "All".

 

-- Mobile device (S60 1st and 2nd Edition)

 

    cd to /group

    bldmake bldfiles

    abld build thumb urel

 

    Select the PKG files according to your SDK. The ones that end with _20.pkg work in

    S60 2nd Edition and the ones with _10.pkg in S60 1st Edition.

    Note that there is no need to sign these SIS files.

 

    cd to /RecognizerEx_xx/sis

    Edit the RecognizerEx_xx.pkg's paths to match those on your system.

    makesis RecognizerEx_xx.pkg

 

    Build and create the .sis files for HandlerApp and TestApp similarly in the /HandlerApp/sis

    and /TestApp/sis directories.

 

   

--Emulator (WINSCW)

    cd to /group

    bldmake bldfiles

    abld build winscw udeb

    Start the emulator.

 

   

--------------------------------------------------------------------------------

 

COMPATIBILITY

 

S60 3rd Edition

S60 2nd Edition

S60 1st Edition

 

TESTED WITH Nokia E60, Nokia N70, Nokia 6630, Nokia 6670, and Nokia 3650.

Created / tested with S60 3rd Edition SDK, S60 2nd Edition SDK and S60 1st Edition SDK.

 

--------------------------------------------------------------------------------

 

VERSION HISTORY                               

 

2.0                 Recognizer example recoded to S60 3rd Edition. Almost all functionality has changed due

to API changes. Document handler and tester applications created.

1.0                 First release of the recognizer example.

 

--------------------------------------------------------------------------------

EVALUATE THIS RESOURCE  

 

Please spare a moment to help us improve documentation quality and recognize the examples you find most valuable,

by rating this resource.