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,