S60 Platform: ECom Plug-in Examples -  ECom_Calculator Example v2.0
-------------------------------------------------------------------------------

This C++ code example is one of the two ECom examples demonstrating how to 
create and use an ECom plug-in from a client application. This specific example implements
a calculator use case. The example consists of three subprojects:

Client: 
A simple Avkon GUI application, which calculates the sum and product of two numbers. 
It uses a custom ECOM interface to do the calculation.

Interface: 
ECOM interface definition for this example. The client uses this 
custom interface to get an instance of the concrete implementation, and the plug-in 
DLL implements the pure virtual Calculate(a,b) method.

Plug-in (EComCalculatePlugin.dll): 
A dll plug-in component, which provides two implementations (sum and multiply)
for a custom ECOM interface. This example uses a default resolver when finding 
the implementation.

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

PREREQUISITES

Symbian C++ basics
ECom basics

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

IMPORTANT FILES/CLASSES

CLIENT:

EComCalculatorAppui.cpp		| CEComCalculatorAppUi::DoEComCalculationL() 
			        | method lets the ECom plug-in do the
     				| calculation.

INTERFACE:

EComInterfaceDefinition.h	| Provides ECom interface definition for the
EComInterfaceDefinition.inl	| calculator client application.

Essentially, the interface is an abstract base class, which defines a pure  
virtual calculation operation TReal Calculate(TReal a, TReal b),
which is used by the client. When the client requests the interface for 
an instance of the concrete implementation, it gives in a string in static 
NewL to provide a hint for the ECOM plug-in framework. The base implementation
for NewL will query the framework to find an appropriate concrete 
implementation. In this example valid hints for NewL are "sum" and "multiply".


PLUG-IN:

EComImplementationMultiply.h 	| Classes CImplementationClassMultiply and  
EComImplementationPlus.h    	| CImplementationClassPlus implement the 
				| interface's Calculate(..) method

101F5465.rss			| Describes the contents of the plug-in DLL

Proxy.cpp			| TImplementationProxy defines where within
				| the DLL the implementations reside

The concrete implementations inherit from the interface. They are the concrete
implementations, which the ECom framework returns to clients.

Implementations are collected within one DLL, which publishes them in a 
resource file. The framework will use the resource file to find a match for the 
given hint. In this example, if the client gives in the "sum" string, the framework 
will find and instantiate CImplementationClassPlus.

Essentially, the resource file defines IMPLEMENTATION_INFO::default_data for 
individual implementations. The field is used by the ECom framework's default 
resolver to find the requested implementation for a client (the string given in 
the client side is compared to "default_data" sections in the plug-in DLL 
resource file). Note that it is also possible to use a custom resolver 
(demonstrated in the ECom_Shape Example).

The ECom framework uses a chart of TImplementationProxy items to map implementation 
IDs to locations of specific implementations instantiation methods (NewL). Each 
implementation ID within TImplementationProxy must match one of the IDs defined in
the 101F5465.RSS resource file.

Note: The name of the compiled resource file must be the same as the UID of the DLL  
      in S60 2nd Edition. In S60 3rd Edition it must match the DLLs name.
      This ensures that the ECom plug-in framework can match the DLL and resource file.


IMPORTANT CLASSES: 

REComSession       |The REcomSession singleton class controls 
                   |the process of identifying (resolution), instantiation, 
                   |and destruction of the interface class implementations 
                   |requested by ECom clients. It manages itself to produce 
                   |a single connection to the ECom framework per thread.
                                
TEComResolverParams             |Used to pass values to a Resolver to aid in the filtering 
                           	|of Interface Implementation plug-ins.    

CEikLabel          |Labels to be displayed

CEikEdwin          |Text boxes for calculation inputs

TResourceReader    |Resource data reading from resource files
                                             

For more information about the ECom plug-in architecture, 
refer to the help of the S60 SDK and the document S60 Platform: ECom Plug-in Architecture 
available at www.forum.nokia.com.

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

KNOWN ISSUES

No known issues related to the example. However, there are some important issues related 
to the UIDs:

The application UIDs are different in S60 2nd and 3rd Editions.
Due to self signing the UID cannot be from the protected range. Because of that all
UIDs are changed from 0x1... to 0xE... in S60 3rd Edition.

UIDs 0xE do not work in S60 2nd Edition so the 0x1 UIDs have to be used for
older SDKs. A "(45) : Number too big for LONG" error is displayed.

If the UID of the plug-in DLL is changed (and correspondingly the name of the rss 
file is changed), the ECom framework may not find the plug-in with the new UID. 
It may be necessary to delete the ECom.ROM.Z.dat and Ecom.idx files in the development
environment folder in the S60 3rd Edition SDK:
\S60_3rd\Epoc32\winscw\c\private\10009D8F

And similarly in S60 2nd Edition SDKs (files ECom.ROM.dat and ECom.idx): 
\Symbian\7.0s\Series60...\Epoc32\wins\c\system\data\Plugins

When the emulator is restarted, the files are recreated.

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

RUNNING THE EXAMPLE

When the EComCalculator application is started, type numbers in the two text boxes. 
Then select the Sum or Multiply command from the Options menu. 

If the ECom implementations are found, the corresponding result will be shown below.

If the plug-in is not installed, the application shows an error asking whether the 
plug-in is installed.

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

BUILD & INSTALLATION INSTRUCTIONS

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

  To test the solution in the device, the results of the .\implementation subproject
  and the .\client subproject must be installed. Both projects provide a 
  package definition file (*.pkg), which can be used to generate the required SIS 
  installation packages. 

  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 3rd Edition)

    cd to \EComCalculator\group
    bldmake bldfiles
    abld build gcce urel


    cd to \EComCalculator\implementation\sis
    Edit EComImplementation_30_gcce.pkg's paths to match those on your system.
    makesis EComImplementation_30_gcce.pkg
    Sign the SIS package 
      - See the SDK Help for information about self-signed .sis packages, or
        www.symbiansigned.com for information about Developer Certificates.
    Install the signed .sis file to an S60 3rd Edition device.

    cd to \EComCalculator\client\sis
    Edit EComCalculator_30_gcce.pkg.pkg's paths to match those on your system.
    makesis EComCalculator_30_gcce.pkg
    Sign the SIS package 
    Install the signed .sis file to an S60 3rd Edition device.

    You can also build the two components separately from their group folders.
    
    The two subprojects also provide SIS files for quick try on a device. 
    They are built using GCCE target.    
    
--Mobile device (S60 2nd Edition)

    Notes:
     - The pkg files expect that ARMI build is completed.
     - IMPORTANT:
       The file paths within the pkg files must be modified to reflect the system setup
       They assume that the local files are relative to 
           \Symbian\7.0s\Series60_v20\Epoc32
     - Required files for the plug-in DLL are generated as follows (assuming ARMI 
       build):
        <epoc32>\data\z\system\libs\plugins\101F5465.RSC
        <epoc32>\release\armi\urel\EComCalculatePlugin.dll
       Both files must be installed to the following location in the 
       device:
        \system\libs\plugins

    cd to \EComCalculator\group
    bldmake bldfiles
    abld build armi urel

    You can build the two components separately from their own group folder.
    
    cd to \EComCalculator\client\sis
    Edit the EComCalculator_2x.pkg's paths to match those on your system.
    makesis EComCalculator_2x.pkg
    Install the SIS file to the device.

    cd to \EComCalculator\implementation\sis
    Edit EComImplementation_2x_armi.pkg's paths to match those on your system.
    makesis EComImplementation_2x_armi.pkg
    Install the SIS file to the device.

    The two subprojects also provide SIS files for quick try on a device. 
    They have been built using ARMI target.
   
--Emulator (WINSCW)
   To run the example in the emulator, the subprojects must be built
   from the .\group directory or all separately from their own group directories.
 
   In a standard way, create the ABLD.bat and build result directories by typing
      >bldmake bldfiles
   Then build the project to the debug emulator by
      >abld build winscw udeb
 
   Note: Build the plug-in first. The client will not fully work if the plug-in 
        DLL is not built. 
    
-------------------------------------------------------------------------------
COMPATIBILITY

S60 3rd Edition
S60 2nd Edition

TESTED WITH  Nokia 6600, Nokia 6630, Nokia N70, and Nokia E60.

Created / tested with S60 2nd Edition SDK,  for Symbian OS, 
Supporting Metrowerks CodeWarrior
and with S60 3rd Edition SDK,  for Symbian OS, for C++, 
Supporting Metrowerks CodeWarrior
-------------------------------------------------------------------------------

VERSION HISTORY         

2.0     Ported from S60 2nd to 3rd Edition.
1.0     First release.

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

ADDITIONAL DOCUMENTATION

S60 Platform: ECom Plug-in Architecture (document)


