S60 Platform: ECom Plug-in Examples - ECom_Shape 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 shows 
drawing different figures. The example consists of three subprojects: 

Client:
A simple Avkon GUI application, which draws objects using the implementations 
through the ECom interface. 

ShapeResolver:
Custom resolver and the custom ECom interface (CShape)

ShapePlugin (shapeimplementation.dll):
A DLL plug-in component, which provides three implementations
for the custom ECom interface.

Because of a requirement for ProtServ capability, the ShapeResolver SIS file 
has to be signed using a developer certificate (available at www.symbiansigned.com).

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

PREREQUISITES

Symbian C++ basics
ECom basics

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

IMPORTANT FILES/CLASSES

The project has an interface definition and three subprojects:
- The interface definition is defined in .\shaperesolver\inc\shapeinterface.h
- The plug-in DLL component subproject is in .\plugin
- The Avkon GUI client subproject is in .\client.
- The custom resolver is defined in .\shaperesolver

CLIENT:

EcomshapeAppUi.cpp              | Avkon GUI implementation
                                | CEcomShapeAppUi::HandleCommandL() Handle menu commands.

CEcomShapeContainer.cpp         | CEcomShapeContainer::DrawDefault(), 
                                | DrawCircle(), DrawSquare(), or DrawTriangle() method
                                | is called when a shape is selected from the Options menu

SHAPERESOLVER:

shaperesolver.cpp               | An implementation of the CResolver definition.

shapeinterface.h	        | Provide ECom interface definition for the
shapeinterface.inl	        | client application.

Essentially, the interface is an abstract base class, which defines the pure  
virtual operation
    virtual void Draw(CWindowGc& aGraphicsContext),
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 (using a resolver which is possibly customized by developers). 
In this example valid hints for NewL are "Circle", "Square", and "Triangle".


PLUG-IN:

circle.h                        | Classes CTriangle, CSquare, and CCircle
square.h                        | implement the CShape interface's Draw(..)
triangle.h                      | method

101F614F.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 provide an
implementation for the Draw(..) function and draw their specific figure. 
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 "Circle" string, 
the framework will find and instantiate the CCircle object. CCircle is 
inherited from CShape so normal polymorphism rules apply here.  

This example uses a custom resolver when finding the implementation in contrast to 
the ECom_Calculator Example.

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).

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 101F614F.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 the resource file.

IMPORTANT CLASSES: 

CShape                   | Custom ECOM interface definition. This interface 
                         | is used by clients to find the specific instance and
                         | display various shapes to the screen. Plug-in implementations
                         | implement the Draw function. 
                                
CResolver                | Abstract base class which is used to identify the 
                         | correct interface implementation based on criteria 
                         | supplied by the client. This base class can be used
                         | to write a client-specific resolver, however this is not 
                         | required as a default implementation is provided within ECom.

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

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

KNOWN ISSUES

There are 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 Edition.
Due to self signing the UID cannot be from the protected range. Because of this, 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, otherwise 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 a 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 ECom_Shape Example is started, select the desired figure from the 
Options menu.

If the ECom implementations are found, the corresponding figure will be drawn.

If the plug-in is not installed, the application will not start (an error message 
shows that the plug-in is missing).

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

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 .\plugin,
  .\shaperesolver, and the .\client subprojects must be installed. 
  All projects provide a 
  package definition file (*.pkg), which can be used to generate required SIS 
  installation packages. 

  If you get a "Certificate error" during the installation of a self-signed 
  package, check that App.Manager -> Settings -> Software Installation is 
  set to "All". 

--Mobile device (S60 3rd Edition)

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

    cd to \EComShape\plugin\sis
    Edit ShapePlugin_30_gcce.pkg's paths to match those on your system.
    makesis ShapePlugin_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 \EComShape\shaperesolver\sis
    Edit ShapeResolver_30_gcce.pkg's paths to match those on your system.
    makesis ShapeResolver_30_gcce.pkg
    Sign the SIS package USING A DEVELOPER CERTIFICATE!
    You can obtain it from www.symbiansigned.com.
    Install the signed .sis file to an S60 3rd Edition device.

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

    You can also build the components separately from their group folders.
    
    The other subprojects than shaperesolver provide a SIS file
    for quick try on a device. The resolver SIS file has to be signed
    using a developer certificate.
    
    
--Mobile device (S60 2nd Edition)

    Notes:
     - The pkg files expect that ARMI build is completed.
     - IMPORTANT:
       The file paths within 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

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

    You can also build the components separately from their own group directory.
    The directory \EComShape\sis contains a single .pkg and SIS file for testing the application
    in S60 2nd Edition devices.

    cd to \EComShape\shaperesolver\sis
    Edit ShapeResolver_2x_armi.pkg's paths to match those on your system.
    makesis ShapeResolver_2x_armi.pkg
    Install the .sis file to an S60 2nd Edition device.

    cd to \EComShape\plugin\sis
    Edit ShapePlugin_2x_armi.pkg paths to match those on your system.
    makesis ShapePlugin_2x_armi.pkg
    Install the .sis file to an S60 2nd Edition device.

    cd to \EComShape\client\sis
    Edit EComShape_2x.pkg's paths to match those on your system.
    makesis EComShape_2x.pkg
    Install the .sis file to an S60 2nd Edition device.

    The subprojects also provide SIS files for quick try on a device. 
    They are built using the 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.
 
   Create the ABLD.bat and build result directories in the standard way by typing
      >bldmake bldfiles
   Then build the project to the debug emulator by typing
      >abld build winscw udeb

   Note: Build the plug-in first. The client will not fully work if the plug-in 
        DLL has not been 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 (published in the package Series 60 Developer Platform 2.0: ECom Plug-in 
Architecture (with example)).

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

ADDITIONAL DOCUMENTATION

S60 Platform: ECom Plug-in Architecture (document)

