S60 Platform ECom Plug-In Architecture v2 0 en

p l a t f o r m
S60 Platform: ECom Plug-in

Architecture
S60
Version 2.0
January 12, 2007
S60 Platform: ECom Plug-in Architecture | 2
Legal notice
Copyright © 2004-2007 Nokia Corporation. All rights reserved.
Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation.
Java and all Java-based marks are trademarks or registered trademarks of Sun
Microsystems, Inc. Other product and company names mentioned herein may be
trademarks or trade names of their respective owners.
Disclaimer
The information in this document is provided “as is,” with no warranties whatsoever,
including any warranty of merchantability, fitness for any particular purpose, or any
warranty otherwise arising out of any proposal, specification, or sample. Furthermore,
information provided in this document is preliminary, and may be changed substantially
prior to final release. This document is provided for informational purposes only.
Nokia Corporation disclaims all liability, including liability for infringement of any
proprietary rights, relating to implementation of information presented in this document.
Nokia Corporation does not warrant or represent that such use will not infringe such
rights.
Nokia Corporation retains the right to make changes to this specification at any time,
without notice.
License
A license is hereby granted to download and print a copy of this specification for
personal use only. No other license to any other intellectual property rights is granted
herein.
Version 2.0 | January 12, 2007

Contents
1. Introduction ......................................................................................................... 5
1.1 Purpose and scope .........................................................................................................5
1.2 ECom architecture and the S60 platforms ......................................................................5
1.3 What is ECom? ...............................................................................................................5
2. Client overview .................................................................................................... 7
3. ECom architecture .............................................................................................. 8
3.1 Interface definition...........................................................................................................8
3.2 Interface implementation.................................................................................................8
3.3 ECom framework ............................................................................................................9
3.3.1 ECom client ............................................................................................................9
3.3.2 ECom server...........................................................................................................9
3.4 Resolution .......................................................................................................................9
4. Example application.......................................................................................... 11
4.1 Structure of example modules ......................................................................................11
4.1.1 Porting to S60 3rd Edition ....................................................................................11
4.1.2 Interface definition and custom resolver...............................................................12
4.1.3 Implementations of the interface definition...........................................................12
4.1.4 Client application ..................................................................................................13
4.2 Building the application .................................................................................................13
5. Interface definition ............................................................................................ 14
5.1 Instantiation functions ...................................................................................................14
5.2 Destroying .....................................................................................................................16
6. Interface implementation collection ................................................................ 17
6.1 Standard DLL entry point ..............................................................................................17
6.2 Implementing interfaces ................................................................................................17
6.3 Implementation factory containers: defining and exporting ..........................................17
6.4 Registry information ......................................................................................................18
6.5 Project file for implementation collection.......................................................................19
7. Custom resolver ................................................................................................ 22
8. Summary ............................................................................................................ 24
9. References ......................................................................................................... 25
10. Terms and abbreviations.................................................................................. 26
11. Evaluate this resource ...................................................................................... 27

Change history
January 23, 2004 Version 1.0 Initial document release
January 12, 2007 Version 2.0 Information about S60 3rd Edition added. The
ECom_Shape example referenced in the
document is separated to its own resource
published at http://www.forum.nokia.com.

1. Introduction
1.1 Purpose and scope
This document describes the ECom framework and discusses why and how it should be
used. Each component of the ECom plug-in framework is explained and an example
application, ECom_Shape (part of S60 Platform: ECom Plug-in Examples [1] available
at www.forum.nokia.com), is used to illustrate the main concepts.
1.2 ECom architecture and the S60 platforms
The ECom plug-in framework was introduced in S60 2nd Edition. S60 1st Edition was
built on Symbian OS v6.1, which does not contain the ECom framework. This framework
was first provided in Symbian OS v7.0s, the underlying OS for S60 2nd Edition. In S60
3rd Edition there are some ECom-related changes. These are discussed in later
chapters.
1.3 What is ECom?
ECom is a client/server framework that provides a service to instantiate, resolve, and

destroy plug-ins. Essentially, it means that functionality that is required by a number of
applications can be encapsulated in a DLL and accessed by multiple clients through an
interface class.
Previously, developers used polymorphic interface DLLs to interact with other services.
This allowed software developers to extend their applications using a defined abstract
interface. Developers were not concerned about the underlying implementation at
compile time. When the application was being executed it would only then select the
correct implementation to use.
However, developers had to create their own framework to:
• Manage the locating, loading, and unloading of DLLs.
• Determine which concrete interface to instantiate.
• Determine which instantiation function to call, etc.
For every instance of a polymorphic interface DLL being used, programmers would have
to provide code that would satisfy the above requirements needed to successfully
instantiate the correct instance. This produces huge amounts of repeated functionality.
ECom removes the complexity and repeated functionality because it is a generic

framework that provides consistent mechanisms to address these shortfalls.
To ensure that the service integrates seamlessly into the application, users of the
service are not made aware that they are dealing with a requesting service. The service
remains "hidden" by making use of instantiation functions, which will construct the
required type of object.
The application framework in releases prior to S60 3rd Edition supported many types of
plug-ins, including GUI applications that were implemented as polymorphic DLLs. Under
platform security, this simple use of polymorphic DLLs is avoided, as the polymorphic
DLL would need security capabilities at least as great as its loading process (which
would be high). This could unnecessarily restrict who could use the framework. A

solution is to change the DLL to be an EXE, which can run as a process with just those
security capabilities it needs.
Frameworks used to search a directory (or directories) to find polymorphic DLLs. With
platform security, all binaries are located in \sys\bin\, and only processes with the
AllFiles capability are able to read from that location. This means that most processes
are not able to scan for binaries themselves.
The solution is to change the DLL into an ECom plug-in. ECom provides a means for
plug-ins to register that they exist and that they support a particular interface, and a
means for processes to discover and load appropriate plug-ins.

2. Client overview
The ECom framework provides a seamless interoperation between applications and
plug-ins. This means that clients are not made aware that they are employing the ECom
framework when using the plug-in. The clients' only concern is how the plug-in behaves
and how to interact with it. This is very important, as users want to easily extend their
applications without worrying about loading and configuring plug-ins they might want to
use.
The interaction between ECom and plug-ins is hidden through the use of abstract
interfaces and instantiation functions. These are combined to create an interface
definition. This will be discussed in much greater detail later, but below is an example of
an interface definition (CShape) implemented in the ECom_Shape code example (part of
S60 Platform: ECom Plug-in Examples [1]):
class CShape : public CBase
{
public:
// Instantiation function – will load explicit shape
static CShape* NewL();
// Instantiation function – requires some sort of identifier
static CShape* NewL(const TDesC& aIdentifier);
// Destructor
virtual ~CShape();
// Draws the shape to screen
virtual void Draw(CWindowGc& aGraphicsContext) = 0;
private:
// Private details...
};
The function SomeFunctionBeingCalled(), shown below, demonstrates how the

interface definition is used. The client requests an instance of an object of type CShape,
by calling the CShape::NewL() instantiation function. The instantiation function will
return the default implementation of CShape. The user then proceeds to Draw() the
shape to the screen. Once the operations between the application and CShape object
have been completed, the CShape object is destroyed:
void CClientApplication::SomeFunctionBeingCalled()
{
...
CShape* shape = CShape::NewL();
CleanupStack::PushL(shape);
shape->DrawL(gc);
CleanupStack::PopAndDestroy(shape);
...
}
The client is not exposed to the ECom framework and is given the appearance that this
is a conventional object being created, used, and destroyed. The only noticeable
difference is that the CShape::Draw() is a pure abstract method. The CShape class
definition will be discussed in more detail in Chapter 5.

3. ECom architecture
This chapter provides a general introduction to the various components required by the
ECom framework to function correctly. Each item will be identified and briefly discussed.
The ECom architecture consists of the following components:
Interface definition
Interface implementation
ECom framework
Resolution
3.1 Interface definition
The interface definition, which makes use of ECom, serves two purposes:
It defines the behavior of the plug-in. The functions implemented will define
the services provided by the plug-in. These functions are generally
implemented as pure abstract functions, which allow the interface definition
to have multiple concrete implementations installed on the device.
It defines instantiation functions. These functions are used to determine what

concrete implementation to instantiate using the ECom framework. Examples
of instantiation functions include NewL(), OpenL(), etc.
Note: Instantiation functions do not explicitly instantiate the object, but issue a
request to the ECom framework, which returns a TAny (void*) object that must be
reinterpreted (cast) to the interface definition.
To implicitly determine which implementation function to use, ECom is given, at run time,
a cue. This cue is used in a process called resolution (described in Section 3.4) to
identify the concrete implementation to be constructed.
3.2 Interface implementation
An interface implementation is a concrete class that implements the interface definition.

This provides the actual service defined by the interface definition.
It is important to note that it is possible, indeed usual, to implement more than one
concrete implementation. Where more than one concrete implementation is provided,
they are referred to as an interface implementation collection.
In order to interact with the concrete classes, the ECom framework requires the
following:
• An array of instantiation functions; for more information, see Section 6.3.
• A published compiled registry information resource file that list its

implementation and properties; for more information, see Section 6.4.

3.3 ECom framework
The ECom framework provides the ability to resolve and instantiate the correct
implementation of the interface definition at run time. It uses the conventional
client/server architecture.
3.3.1 ECom client
The ECom client provides a well-defined interface that controls the

resolution/identification, instantiation, and destruction of the requested interface
using REComSession.
Once the request to instantiate an implementation occurs, all of the interface

definition calls will use the instantiated implementation.
When the instantiated object is destroyed, it must notify the ECom framework.
Note: The REComSession does not allow more than one connection to the ECom
server per thread.
3.3.2 ECom server
The ECom server manages the client’s request to instantiate, resolve, and
destroy the requested plug-in.
The server consists of a repository of registered implementations. This includes

metadata used to resolve the correct implementation requested by the client. The
implementations and resource files for the ECom plug-ins are stored in the
following directory prior to Symbian OS v9.1:
\systems\libs\plugins
In Symbian OS v9.1 and newer the implementations are stored in:

\sys\bin\
and the resource files are stored in:

\Resource\Plugins\
The server is constantly monitoring which implementations have been registered

or removed. An implementation can be removed at any time, for example if a
drive is physically removed or swapped.
The server is notified via the file server if there has been some sort of change.
The server then determines what changes have been made by scanning through
the appropriate directories using a non-intrusive search that does not affect
processing. If it notices any changes, it notifies the repository and performs the
necessary modifications.
3.4 Resolution
Each concrete implementation of the interface definition provides metadata (name,

description, version, etc.), which is used to describe and identify the interface; this is
known as registry information. (Further information can be found in Section 6.4.) This
data provides the necessary information for the ECom server to locate the correct
concrete implementation by looking up the interface’s UID or a text cue. If a text cue is
used, the ECom framework uses a resolver to determine which implementation to use by
comparing the cue to the registered metadata.

The ECom framework provides a default resolver for selecting the most appropriate
implementation.
Note: The default resolver does a case-sensitive search against the cue provided.
Apart from finding the “best-fit“ implementation, the user can also request a list of
implementations. This will allow the client to iterate through the list and determine which
implementation is most suited for the application needs.
It is also possible to create a custom resolver. This allows developers to specify their
own selection algorithm when determining which interface to use. More information can
be found in Chapter 7.

4. Example application
Use of the ECom framework is best explained by means of an example implementation.
In this section, the structure and functions of the ECom Shape example are discussed.
ECom_Shape and another example, ECom_Calculator, are included in S60 Platform:
ECom Plug-in Examples [1] available at www.forum.nokia.com.
The example application is based on the classic object-oriented shape example. An

application will issue a request for a particular instance of a shape and for a picture of
that shape to be displayed on the screen. Once the application has an instance of a
shape object, it is not concerned about how it has been implemented but rather how it
behaves.
ECom_Shape is a trivial example of the use of ECom. However, it does demonstrate all
the key features and will therefore be used to help explain the various ECom
components as they are discussed throughout the remainder of this document. It is
important to note that, in practice, ECom would not be employed for such a simple
application; it should only be used when there are multiple clients wanting to access the
functionality provided by a plug-in.
The ECom_Shape application illustrates how to:
Create a plug-in interface definition
Create implementations of the plug-in interface
Create a custom resolver
Create a client using the plug-in
4.1 Structure of example modules
The application has been split into three different directories:
• \client – Interface definition and custom resolver
• \plugin – Implementations of the interface definition
• \shaperesolver – Application that interacts with the definition
4.1.1 Porting to S60 3rd Edition
When checking the example codes, you will see that the example application’s
UID is changed from 0x101F614D to 0xE01F614D in S60 3rd Edition. This is
because of the possibility for self signing where the UIDs have to be in the
unprotected range.
In addition to the normal changes that are required when porting an S60
application to 3rd Edition there are only a few other additions or changes. These
are discussed next.
The call of REComSession::FinalClose() has been added in the AppUi’s

destructor so that the plug-in DLL can be unloaded:
CEcomShapeAppUi::~CEcomShapeAppUi()
{
if (iAppContainer)

{
RemoveFromStack( iAppContainer );
delete iAppContainer;
}
#ifdef __SERIES60_3X__
REComSession::FinalClose();
#endif
}
Target type is changed from ECOMIIC to PLUGIN in the S60 3rd Edition MMP file.
The resource file definition has also been changed to:
// keep the name for backward compatibility
START RESOURCE 101F5465.RSS
// set the new name for the compiled resource
TARGET EComCalculatePlugin.rsc
END
Macro IMPLEMENTATION_PROXY_ENTRY is used in the implementation table:

const TImplementationProxy ImplementationTable[] =
{
IMPLEMENTATION_PROXY_ENTRY(0x101F614E,
CShapeResolver::NewL)
#else
{{0x101F614E}, CShapeResolver::NewL}
#endif
};
The DLL file and the resource file places have also been changed to \sys\bin\
and \Resource\Plugins\.
4.1.2 Interface definition and custom resolver
This directory provides the interface definition CShape and the custom resolver
CShapeResolver.
The CShape interface definition is the ECom plug-in interface used by all client
applications, and all concrete implementations must derive from this. It provides
two instantiation functions and one abstract method.
The first instantiation method explicitly requests an interface by passing the

interface’s UID. The second instantiation method accepts a cue that will be used
by a custom resolver to acquire the correct interface. The abstract method
accepts a CWindowGc object that is used to draw the object.
A custom resolver called CShapeResolver is also implemented. Since a

resolver is a plug-in, it must also provide a registration information resource file
(101F614D.rss) and an exported factory table (Proxy.cpp).
4.1.3 Implementations of the interface definition
There are three implementations of the CShape interface definition: CCirlce,

CSquare, and CTriangle. Each implements the abstract function Draw(),
which draws the shape of the object to the screen.
The implementations also contain a registration information resource file

(101F614F.rss) and an exported factory table (Proxy.cpp).

4.1.4 Client application
The client application demonstrates how to interact with the plug-in.
4.2 Building the application
Ensure that the S60 2nd Edition SDK or newer for Symbian OS has been installed, and
then download the ECom_Shape example (part of S60 Platform: ECom Plug-in
Examples [1] ) and place it in a directory located on the same drive where the SDK has
been installed. Once this has been completed, follow the building instructions in the
example’s release notes.
Note: When installing the ECom plug-in/custom resolver DLL and ECom plug-
in/custom resolver compiled resource file for a device, ensure that they are placed
in the \system\libs\plugins directory prior to Symbian OS v9.0. In Symbian OS
v9.1 (S60 3rd Edition) the DLL is placed in \sys\bin\ and the compiled resource file
in \resource\plugins\.

5. Interface definition
An interface definition defines the behavior of the plug-in. Accordingly when declaring
the interface definition, the following features must be provided:
• Functionality provided by the service. These methods are generally pure abstract
methods.
• Instantiation mechanisms.
Note: The definition must always contain a TUid data member; this is used to identify
the instantiated object for destruction.
Below is an example of an ECom-enabled definition, taken from the ECom_Shape

example application (part of S60 Platform: ECom Plug-in Examples [1].) This example
interface definition is very simple and just enables the client to request that a particular
shape be drawn to the screen. This service is offered through the const abstract Draw()
method. The instantiation mechanism required is provided through the NewL() methods.
// Forward declaration
class CWindowGc;
class CShape : public CBase
{
public:
static CShape* NewL();
static CShape* NewL(const TDesC8& aMatch);
virtual ~CShape();
virtual void Draw(CWindowGc& aGraphicsContext) const = 0;
private:
TUid iDtor_ID_Key;
};
The interface definition is derived from CBase, but this is not mandatory; for example,
the class could be derived from CActive, RHandleBase, etc.
If the interface definition is derived from CBase, then, in keeping with convention, a static
factory method called NewL() would be implemented for creation, and a destructor for
cleanup. If the interface class derives from RHandleBase, then OpenL() and Close()
methods should be implemented.
Generally, abstract classes do not contain instantiation functions, but, in the case of an
ECom interface definition, this is required. The reason for the instantiation function is to
issue a request to the ECom framework to create an instance of the correct concrete
plug-in.
The abstract method(s) defined in the interface, that is, Draw(), have no explicit
implementation. The concrete plug-in implements the actions of the method call.
5.1 Instantiation functions
The interface definition class, CShape, contains two instantiation methods. The first
instantiation method requests the default implementation of CShape — in the
ECom_Shape example (part of S60 Platform: ECom Plug-in Examples [1]), CCircle is
defined as the default implementation. To ensure that the correct instance is retrieved,

the CCircle UID is passed to the ECom service. (The CCircle UID is defined in a
resource file; this is discussed further in Section 6.4.)
CShape* CShape::NewL()
{
const TUid KCCircleInterfaceUid = {0x101F6150};
TAny* interface = REComSession::CreateImplementationL (
KCCircleInterfaceUid, _FOFF (CShape, iDtor_ID_Key));
return reinterpret_cast <CShape*> (interface);
}
The instantiation function makes use of REComSession class’s static method

CreateImplementationL().
CreateImplementationL has several overloaded methods that allow for:
Selection of a specific interface.
Passing of parameters to the implementation creation function.
A cue to be passed to indicate which interface to use.
This particular use of CreateImplementationL passes two parameters, a UID to

identify the requested implementation and the offset used to pass the Idtor_ID_Key,
which is used to identify the created instance. The IDtor_ID_Key is used to notify the
ECom framework once the object is destroyed; more information can be found in Section
5.2. The _FOFF macro is used to calculate the offset of IDtor_ID_Key from CShape.
REComSession::CreateImplementationL() returns a TAny pointer that will be

reinterpreted (cast) into the definition type. It also populates Idtor_ID_Key.
The above example returns an instance of the CCircle implementation by specifying

the UID of CCircle. The second instantiation function defined by the interface,
NewL(const TDesC& aMatch), makes use of a custom resolver to determine which
interface the client requires. To use the custom resolver, a cue (aMatch) is passed to
enable the framework to determine which interface to select. In the ECom_Shape
example, a client could request a CTriangle object using a cue, for example:
LIT8 (KTriangleText,"Triangle");
CShape* triangle = CShape::NewL (KTriangleText);
The implementation of the overloaded NewL() provided by CShape takes this cue as a
parameter:
CShape* CShape::NewL (const TDesC8& aMatch)
{
const TUid KCShapeInterfaceUid = {0x101F614C};
const TUid KCShapeResolverUid = {0x101F614E};
TEComResolverParams resolverParams;
resolverParams.SetDataType (aMatch);
resolverParams.SetWildcardMatch (ETrue);
TAny* interface = REComSession::CreateImplementationL
(KCShapeInterfaceUid, _FOFF (CShape, iDtor_ID_Key),
resolverParams, KCShapeResolverUid);
return reinterpret_cast <CShape*> (interface);
}
The overloaded NewL() method creates a TEComResolverParams object. This

encapsulates the resolver’s cue, which is set by calling the
resolverParams.SetDataType() method. In the ECom_Shape application (part of
S60 Platform: ECom Plug-in Examples [1]) all the cues are simply the name of the type
of shape required, that is “Square,” “Circle,” and “Triangle.” The ability to include
wildcard characters in the cue text is supported. The resolver parameter object must be

set to use wildcards through a call to resolverParams.SetWildcardMatch() with

ETrue passed through.
Once the TEComResolverParams object has been configured properly, it is passed,

along with the UID of the interface definition, to the
REComSession::CreateImplementationL() method. The requested interface is then
located and constructed. A TAny pointer is then returned and the iDtor_ID_Key
populated as a means of identification. The TAny pointer being returned is reinterpreted
into the definition type.
If no interface implementation is found, the ECom framework leaves. The error code
returned is KErrNotFound.
The above examples are taken from the ECom_Shape project and can be found at
/EComShape/shaperesolver/inc/shapeinterface.inl.
5.2 Destroying
The interface definition implements a virtual destructor. It is important that when an

object is going to be destroyed it notifies the ECom framework by calling
REComSession::DestroyedImplementation() and passing through the
iDtor_ID_Key for identification.
CShape::~CShape()
{
REComSession::DestroyedImplementation (iDtor_ID_Key);
}

6. Interface implementation collection

An interface implementation collection is a set of concrete plug-ins that uses the
interface definition to define its behavior. The interface implementation collection must
provide the following:
• Standard DLL entry point (in S60 2nd Edition)
• Implementing interfaces
• Implementation factory container: defining and exporting
• Registry information
• Implementation collection project file
In the ECom_Shape example (part of S60 Platform: ECom Plug-in Examples [1]), the
interface implementation collection comprises three implementations, namely those for
circle, square, and triangle (the implementation classes are defined in
/EComShape/plugin.).
6.1 Standard DLL entry point
Since a plug-in is a DLL, it had to provide a standard entry point for the DLL before S60
3rd Edition. The following example shows how the entry point is defined for the older
SDKs:
TInt E32DLL()
{
return KErrNone;
}
6.2 Implementing interfaces
When creating a concrete implementation of the defined interface it is necessary to:
• Derive from the interface definition.
• Implement the pure abstracted methods.
• Create conventional instantiation functions, that is, NewL() and ConstructL().
The ECom_Shape example provides three concrete implementations of the interface

definition, namely CCircle, CSquare, and CTriangle. The class definitions can be
found in the directory /EComShape/plugin/inc.
6.3 Implementation factory containers: defining and exporting
The ECom framework needs to determine the factory function required to instantiate the
correct instance. This is handled by providing a function that returns a pointer to an array
of TImplementationProxy. The TImplementationProxy is a structure that contains a
TUid used to identify the implementation and a TAny pointer that points to the
instantiation function. The array of TImplementationProxy values defined for
ECom_Shape is:

const TImplementationProxy implementationTable[] =

{
//{{0x101F614E}, (TProxyNewLPtr) CShapeResolver::NewL}
IMPLEMENTATION_PROXY_ENTRY(0x101F6150, CCircle::NewL),
IMPLEMENTATION_PROXY_ENTRY(0x101F6151, CSquare::NewL),
IMPLEMENTATION_PROXY_ENTRY(0x101F6152, CTriangle::NewL)
#else
{{0x101F6150}, CCircle::NewL},
{{0x101F6151}, CSquare::NewL},
{{0x101F6152}, CTriangle::NewL}
#endif
};
Notice the difference between S60 3rd Edition and the older SDKs: The macro
IMPLEMENTATION_PROXY_ENTRY is used in casting the ECom instance type to a
TProxyNewLPtr. The UIDs in the array must be the same as the
implementation_uids defined in the registration resource file; this is discussed in
Section 6.4.
To export the container, the following exported function must be called:
const TImplementationProxy* ImplementationGroupProxy(TInt&

aTableCount);
It returns a pointer to the first item in the array and the amount of elements contained in
the array, for example:
EXPORT_C const TImplementationProxy* ImplementationGroupProxy (TInt&

aTableCount)
{
aTableCount = sizeof (implementationTable) /
sizeof (TImplementationProxy);
return implementationTable;
}
The implementation factory container and export function for the ECom_Shape example
(part of S60 Platform: ECom Plug-in Examples [1]) can be found at
/EComShape/plugin/src/proxy.cpp.
6.4 Registry information
For the plug-in to register with the ECom framework, a resource file must be created and
compiled to list all of the plug-in properties. Thus, when creating an interface collection
resource file (/EComShape/plugin/data/101F614F.rss), the following must occur:
In S60 3rd Edition the compiled resource file is named after the DLL, as in
shapeimplementation.rsc. In S60 2nd Edition SDKs the resource file had to be given
the same name as the third UID of the DLL. In the ECom Shape example, the third UID
is 0x101F614F, therefore the resource file would be named 101F614F.rss.
The needed resource structures can be found in RegistryInfo.rh.
A single REGISTRY_INFO structure is required. This declares the interface

implementations available in the interface collection. It contains the dll_uid and an
array of INTERFACE_INFO structures.
INTERFACE_INFO declares the implementations available for a particular interface. It

contains an interface_uid and an array of IMPLEMENTATION_INFO structures. The
interface_uid is a UID that identifies the interface definition.

IMPLEMENTATION_INFO declares details of an interface implementation. This structure

stores information that is used to identify the implementation explicitly or by resolution. It
also contains general metadata information about the interface.
Note: The default resolver uses the default_data attribute to resolve plug-in
interface lookups, but a custom resolver can also use opaque_data to search
against.
#include "RegistryInfo.rh"
RESOURCE REGISTRY_INFO theInfo
{
// UID for the DLL
dll_uid = 0xE01F614F;
#else
dll_uid = 0x101F614F;
#endif // Declare array of interface info
interfaces =
{
INTERFACE_INFO
{
// UID of interface that is implemented
interface_uid = 0x101F612C;
implementations =
{
// Info for CCircle
IMPLEMENTATION_INFO
{
implementation_uid = 0x101F6150;
version_no = 1;
display_name = "Circle shape";
default_data = "CIRCLE";
opaque_data = "";
},
// Info for CSquare
IMPLEMENTATION_INFO
{
version_no = 1;
display_name = "Square shape";
default_data = "SQUARE";
opaque_data = "";
},
// Info for CTriangle
IMPLEMENTATION_INFO
{
version_no = 1;
display_name = "Triangle shape";
default_data = "TRIANGLE";
opaque_data = "";
}
};
}
};
}
6.5 Project file for implementation collection
When writing a project file (*.mmp file) for the implementation collection, it must contain
the following details and build options.
TARGET – Specifies the target’s name.

TARGETTYPE – Specifies the target’s build. For an ECom implementation collection,

ECOMIIC is specified in S60 2nd Edition and PLUGIN in S60 3rd Edition.
UID – Specifies the ECom recognition DLL UID (0x10009D8D) and the UID for the
DLL.
RESOURCE – Specifies the implementation registration file.
SYSTEMINCLUDE – Specifies the include path for ECom.
LIBRARY– Specifies ecom.lib to link against.
The following example is for S60 3rd Edition:

TARGET shapeimplementation.dll
TARGETTYPE PLUGIN
// ECom Dll recognition UID followed by the unique UID for this dll
UID 0x10009D8D 0xE01F614F
SECUREID 0xE01F614F
//there are no capabilities required but note that the application
//using the ECom must have less or the same capabilities that the
//ECom DLL has (which in this case is none).
CAPABILITY NONE
SOURCEPATH ..\src
//SOURCE main.cpp //DLL entry point not required in S60 3rd
Edition
SOURCE proxy.cpp
SOURCE circle.cpp
SOURCE square.cpp
SOURCE triangle.cpp
USERINCLUDE ..\inc
SYSTEMINCLUDE \epoc32\include
START RESOURCE ..\data\101F614F.RSS
TARGET shapeimplementation.rsc
END
LIBRARY euser.lib ECom.lib
The following example is for S60 2nd Edition:

TARGET shapeimplementation.dll
TARGETTYPE ECOMIIC
// ECom Dll recognition UID followed by the unique UID for this dll
UID 0x10009D8D 0x101F614F
SOURCEPATH ..\src
SOURCE main.cpp
SOURCE proxy.cpp
SOURCE circle.cpp
SOURCE square.cpp
SOURCE triangle.cpp
USERINCLUDE ..\inc
SYSTEMINCLUDE \epoc32\include
SOURCEPATH ..\data
RESOURCE 101F614F.RSS
LIBRARY euser.lib ECom.lib

Note: If the UID of the plug-in DLL is changed (and correspondingly the name of rss
file is changed), the ECOM framework may not find the plug-in with the new UID. It
may be necessary to delete the following files from your SDK:
ECom.ROM.dat
ECom.idx
The files are in development environment folder
\Series60_v20\Epoc32\wins\c\system\data\Plugins
In S60 3rd Edition the files ECom.ROM.Z.dat and ECom.idx are located in:
\S60_3rd\Epoc32\winscw\c\private\10009D8F
This may also apply to real devices. Hence changing the UIDs should be avoided, if
possible.

7. Custom resolver
As previously mentioned, it is possible to create custom resolvers. A custom resolver
can be created if a different selection algorithm is required, for example the
ECom_Shape application (part of S60 Platform: ECom Plug-in Examples [1]) implements
a case-insensitive selection.
Custom resolvers are themselves interface implementations. They are concrete

implementations of the ECom CResolver interface definition. As when implementing
normal ECom interface definition plug-ins, you must provide registration resource
information, a UID, and a factory container and function.
When implementing the concrete implementation of CResolver, the following must be

defined and implemented:
• A factory function that takes MPublicRegistry object.
• An implementation of IdentifyImplementationL() and ListAllL().
• In S60 3rd Edition the ProtServ capability is required.
The factory method NewL() is responsible for creating an instance of the customer
resolver. The MPublicRegistry object passed by the factory function gives the custom
resolver access to a list of implementations of a specified interface.
The IdentifyImplementationL() method identifies the most appropriate

implementation of a specified interface definition. To do this, the MPublicRegistry
object iRegistry is queried for a list of CImplementationInformation objects. The
CImplementationInformation objects contain information provided by the registry
information resource file (the registry information is discussed in Section 6.4). The list is
then iterated through and compared against the data provided by
aAdditionalParameters. Once a successful match has been found, the UID of the
matching interface is returned; otherwise, KnullUid is returned.
The ListAllL()method returns a list of all of the matching implementations. The same
concept applies as in IdentifyImplementationL(), except it will return a list of
CImplementationInformation objects back to the ECom server framework.
The custom resolver defined for the ECom_Shape example is shown here:
class CShapeResolver : public CResolver

{
public:
static CShapeResolver* NewL(MPublicRegistry& aRegistry);
virtual ~CShapeResolver();
virtual TUid IdentifyImplementationL(TUid aInterfaceUid,
const TEComResolverParams& aAdditionalParameters) const;
virtual RImplInfoArray* ListAllL(TUid aInterfaceUid,
private:
CShapeResolver(MPublicRegistry& aRegistry);
TUid Resolve(const RImplInfoArray& aImplementationsInfo,

TBool Match(const TDesC8& aImplementationType, const TDesC8&
aMatchType, TBool aUseWildcards) const;

};
The Resolve() and Match() functions in the CShapeResolver class contain the
algorithms used to determine which implementation to use. Resolve() cycles through
the implementations list and calls Match() to determine if that implementation can be
used (the method of determination in this case is by descriptor comparison).
When creating the registration resource, the interface_uid must always be defined as
0x10009D90. This value associates it to the CResolver interface. The resolver
registration resource defined for the ECom_Shape example
(/EComShape/shaperesolver/data/101F614D.rss) is shown:
#include "RegistryInfo.rh"
RESOURCE REGISTRY_INFO theInfo
{
dll_uid = 0xE01F614D;
#else
dll_uid = 0x101F614D;
#endif interfaces =
{
INTERFACE_INFO
{
// Interface UID of resolvers
interface_uid = 0x10009D90;
implementations =
{
IMPLEMENTATION_INFO
{
implementation_uid = 0x101F614E;
version_no = 1;
display_name = "";
default_data = "";
opaque_data = "";
}
};
}
};
}
Note that display_name, default_data, and opaque_date contain no data, as they

are not used.
The usage of default resolver is demonstrated in ECom_Calculator example (part of S60

Platform: ECom Plug-in Examples [1]).

8. Summary
This document provides an overview of what is required when using the ECom
framework. To recap, the ECom framework is a client/server architecture that provides a
service to instantiate, resolve, and destroy plug-in instances.
Users using the interface definition are unaware that they are interacting with the ECom
framework because the interface provides instantiation functions.
The instantiation functions implement the request to the framework, which will return an
instance of the requested implementation. When the request is issued, it uses ECom’s
client REComSession to interact with the server.
The ECom server constantly monitors to see what plug-ins are available on the device. It
stores information that is used to resolve interfaces explicitly and implicitly.
The framework provides a default resolver, which is used to resolve the “best fit”
implementations. The user can implement a customized resolver used to determine the
“best fit” implementations. When implementing a customize resolver, it must derive from
CResolver (interface definition).

9. References
[1] S60 Platform: ECom Plug-In Examples, available at www.forum.nokia.com
[2] ECom-related information in SDK help

1 0 . Te r m s a n d a b b r e v i a t i o n s
Term or Meaning
abbreviation
DLL Dynamic Link Library

11. Evaluate this resource

Please spare a moment to help us improve documentation quality and recognize the
resources you find most valuable, by rating this resource.

S60 Platform ECom Plug-In Architecture v2 0 en

Загружено:

Сведения о документе

Исходное описание:

Оригинальное название

Авторское право

Доступные форматы

Поделиться этим документом

Поделиться или встроить документ

Параметры публикации

Этот документ был вам полезен?

Это неприемлемый материал?

Авторское право:

Доступные форматы

S60 Platform ECom Plug-In Architecture v2 0 en

Загружено:

Авторское право:

Доступные форматы

p l a t f o r m

S60 Platform: ECom Plug-in

Copyright © 2004-2007 Nokia Corporation. All rights reserved.

Version 2.0 | January 12, 2007

Version 2.0 | January 12, 2007

January 23, 2004 Version 1.0 Initial document release

Version 2.0 | January 12, 2007

1.1 Purpose and scope

1.2 ECom architecture and the S60 platforms

1.3 What is ECom?

ECom is a client/server framework that provides a service to instantiate, resolve, and

However, developers had to create their own framework to:

• Manage the locating, loading, and unloading of DLLs.

• Determine which concrete interface to instantiate.

• Determine which instantiation function to call, etc.

ECom removes the complexity and repeated functionality because it is a generic

Version 2.0 | January 12, 2007

Version 2.0 | January 12, 2007

The function SomeFunctionBeingCalled(), shown below, demonstrates how the

Version 2.0 | January 12, 2007

The ECom architecture consists of the following components:

3.1 Interface definition

 It defines instantiation functions. These functions are used to determine what

3.2 Interface implementation

An interface implementation is a concrete class that implements the interface definition.

• An array of instantiation functions; for more information, see Section 6.3.

• A published compiled registry information resource file that list its

Version 2.0 | January 12, 2007

3.3 ECom framework

3.3.1 ECom client

The ECom client provides a well-defined interface that controls the

Once the request to instantiate an implementation occurs, all of the interface

3.3.2 ECom server

The server consists of a repository of registered implementations. This includes

In Symbian OS v9.1 and newer the implementations are stored in:

and the resource files are stored in:

The server is constantly monitoring which implementations have been registered

Each concrete implementation of the interface definition provides metadata (name,

Version 2.0 | January 12, 2007

Version 2.0 | January 12, 2007

The example application is based on the classic object-oriented shape example. An

The ECom_Shape application illustrates how to:

 Create a plug-in interface definition

 Create implementations of the plug-in interface

 Create a custom resolver

 Create a client using the plug-in

4.1 Structure of example modules

The application has been split into three different directories:

• \client – Interface definition and custom resolver

• \plugin – Implementations of the interface definition

• \shaperesolver – Application that interacts with the definition

4.1.1 Porting to S60 3rd Edition

The call of REComSession::FinalClose() has been added in the AppUi’s

Version 2.0 | January 12, 2007

Macro IMPLEMENTATION_PROXY_ENTRY is used in the implementation table:

4.1.2 Interface definition and custom resolver

The first instantiation method explicitly requests an interface by passing the

A custom resolver called CShapeResolver is also implemented. Since a

4.1.3 Implementations of the interface definition

There are three implementations of the CShape interface definition: CCirlce,

The implementations also contain a registration information resource file

Version 2.0 | January 12, 2007

It defines instantiation functions. These functions are used to determine what

Create a plug-in interface definition

Create implementations of the plug-in interface

Create a custom resolver

Create a client using the plug-in

Selection of a specific interface.

Passing of parameters to the implementation creation function.

A cue to be passed to indicate which interface to use.