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 applications 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 classs
       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 at http://www.forum.nokia.com/main/1%2C%2C90%2C00.html?surveyId= 3e6c5f1f-1fb3-4c04-96ad-40979c7f2665/S60_Platform_Document_Handler_Example_v1_0_en.zip


