Professional Documents
Culture Documents
S60
Version 2.0
January 12, 2007
S60 Platform: ECom Plug-in Architecture | 2
Legal notice
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.
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 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
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.
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.
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.
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.
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 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.
Interface definition
Interface implementation
ECom framework
Resolution
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.
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.
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:
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.
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.
The ECom server manages the client’s request to instantiate, resolve, and
destroy the requested plug-in.
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
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.
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.
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.
{
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
The DLL file and the resource file places have also been changed to \sys\bin\
and \Resource\Plugins\.
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.
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.
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.
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 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);
}
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
CShape::~CShape()
{
REComSession::DestroyedImplementation (iDtor_ID_Key);
}
• Implementing interfaces
• Registry information
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.).
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;
}
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:
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.
It returns a pointer to the first item in the array and the amount of elements contained in
the array, for example:
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.
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.
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
#ifdef __SERIES60_3X__
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
{
implementation_uid = 0x101F6151;
version_no = 1;
display_name = "Square shape";
default_data = "SQUARE";
opaque_data = "";
},
// Info for CTriangle
IMPLEMENTATION_INFO
{
implementation_uid = 0x101F6152;
version_no = 1;
display_name = "Triangle shape";
default_data = "TRIANGLE";
opaque_data = "";
}
};
}
};
}
When writing a project file (*.mmp file) for the implementation collection, it must contain
the following details and build options.
UID – Specifies the ECom recognition DLL UID (0x10009D8D) and the UID for the
DLL.
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
\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.
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 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:
};
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
{
#ifdef __SERIES60_3X__
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 = "";
}
};
}
};
}
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
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