14

ECOM

Go on, get out! Last words are for fools who haven’t said enough!

Karl Marx

In Chapter 13, I described polymorphic ”plug-in” DLLs which implement an abstract interface and are dynamically loaded at run-time to extend a ”framework” process. There are three roles associated with an extensible plug-in framework:

•an interface, which defines a service

•an implementation of that interface (within a polymorphic plug-in DLL); the specifics of an implementation may not be known until run-time and several implementations of the interface may exist

•a framework, which provides clients with access to all the implementations of a specific interface, including a way to determine which implementations are available (resolution), and to manage the creation and destruction thereof.

Prior to Symbian OS v7.0, each framework used its own custom code to identify the plug-in type and the nature of the specific implementation and to load and unload individual plug-ins as appropriate. To simplify such framework code, ECOM was added to Symbian OS v7.0.

14.1 ECOM Architecture

ECOM is a generic and extensible framework by which abstract interfaces can be defined and their implementations identified, loaded and managed. Frameworks can delegate their plug-in identification and instantiation to ECOM, and do not have to duplicate complex code which does not bear any direct relevance to the required behavior of the framework itself. The architecture:

• Identifies all the concrete implementations of a particular interface.

234

ECOM

•Allows a client of that interface to specify dynamically which interface implementation should be used. The selection process is called resolution. ECOM provides a default resolver but interface definitions can provide their own specialized resolvers where required.

•Instantiates an instance of the concrete class which implements that interface by calling the appropriate factory function.

The class is implemented in an ECOM plug-in DLL and ECOM loads it into the process in which the caller is running. The plug-in may be loaded by a number of different clients running simultaneously in different processes. ECOM uses reference counting to manage this, and unloads it when all its clients have released it.

The ECOM architecture is used transparently by interface clients without the need for them to call any ECOM-specific functions. ECOM creates an instance of an interface implementation dynamically, either by selecting a default implementation or by using a cue from the client as a way of identifying the particular implementation required. The means by which ECOM identifies and loads the correct plug-in is hidden from the client. Once an object of the concrete class is instantiated, the caller accesses it transparently through the interface. The client does not need to access the concrete class itself, nor does it need to access ECOM directly, although it must link against the ECOM client library (ECOM.lib).

ECOM itself uses a client–server architecture, which is discussed in more detail in Chapters 11 and 12. The ECOM client class, REComSession, provides functions to list, instantiate and destroy interface implementations. A single instance of the ECOM client session exists per thread, and is accessed by interface instantiation and destruction code, which uses a set of static functions.

The ECOM server manages requests to instantiate concrete instances of an interface. By using resource file metadata provided by each ECOM plug-in, it constructs a registry of all interface implementations installed on the device. The server constantly monitors which implementations are available by means of filesystem scanning, which determines when plugins have been added or removed, by installation or on removable media.

An interface implemented by an ECOM plug-in has two characteristic features. Firstly, it is an abstract class that defines a set of one or more pure virtual functions. This is the standard definition of an interface. However, in addition, the interface must also provide one or more factory functions to allow clients to instantiate an interface implementation object.

The factory functions do not instantiate the object directly, because an interface cannot predict which classes will implement it. Instead, the factory functions issue requests to the ECOM framework which, at runtime, instantiates the appropriate implementation class dynamically. As I described above, in order to determine which implementation to

ECOM ARCHITECTURE

235

instantiate, ECOM is given a cue, which may be a UID or some text which is passed to a resolver. Alternatively, a list of all implementations of a particular interface can be returned to the caller, which can then specify the one to use. I’ll illustrate both methods of instantiation in code later in the chapter.

If the only contact you intend to make with ECOM is as an ECOM interface client, the good news is that you don’t need to read any more of this chapter. However, you may find it useful to go to the end, where you’ll find some example code for a typical interface client and a brief summary of the contents of the rest of this chapter.

This chapter discusses how to define an interface and implement it in an ECOM plug-in DLL. I’ll illustrate the main points with example code that defines an abstract base class interface, CCryptoInterface, which can be used to encrypt and decrypt the contents of an 8-bit descriptor.1

I’ll show how ECOM can be used to select dynamically which of two possible concrete implementations of the interface to use. In the example, I’ve assumed that there are just two implementations of the interface, which differ because one uses a cryptography library implemented in software while the other uses a cryptographic hardware module, accessed by means of a device driver. Of course, numerous implementations of this example interface could exist, provided by separate plug-in DLLs, for various cryptography libraries ported to Symbian OS. However, for simplicity, this example implements both concrete classes in a single plug-in DLL.

Figure 14.1 shows the relationship between the client, interface and implementation classes and ECOM, using the classes from the example code for illustration.

			Interface		REComSession::CreateImplementationL()
Interface client
	NewL()	(CCryptoInterface)
	Factory
	function					ECOM Framework
						Resolves
						and
	Implementation			Implementation		instantiates
	(CSoftwareCrypto)			(CHardwareCrypto)

Figure 14.1 Relationship between client, interface and implementation classes and ECOM

1 I invented the fictional CCryptoInterface class, and all the sample code in this chapter, merely as an example of how to use ECOM. Any resemblance to Symbian OS cryptography libraries, living or dead, is purely coincidental.

236

ECOM

14.2Features of an ECOM Interface

Let’s start by considering the features of an ECOM interface:

•As expected, the interface will define a set of pure virtual functions which a concrete instance will implement.

•In addition, the interface must also provide one or more factory functions that pass a cue to ECOM to enable it to instantiate an object of the correct implementation (in the example below, the interface definition has two static NewL() functions).

•The interface must also provide a means for its clients to release it, such as a destructor to allow it to be deleted, or a method such as

Release() or Close().

•An ECOM interface definition must also have a TUid data member which is used internally by ECOM to identify an implementation instance for cleanup purposes.

Here is the definition of the example interface class, CCryptoInterface. You’ll notice that the example interface class is a C class rather than an M class, which is what you may automatically have expected for an abstract interface definition from the discussion of the standard Symbian OS class types in Chapter 1. The reason for this is clear on further inspection, because an ECOM interface class has features which are atypical of an M class, such as the static instantiation method and a TUid data member.

class CCryptoInterface : public CBase

{

public:

enum TAlgorithm { EDES, E3DES, EAES, ERC2, ERC4 };

//Instantiation of a default object of this type IMPORT_C static CCryptoInterface* NewL();

//Instantiation using a cue to identify the implementation to use IMPORT_C static CCryptoInterface* NewL(const TDesC8& aCue);

IMPORT_C virtual CCryptoInterface();

// List all implementations of this interface IMPORT_C static void

ListImplementationsL(RImplInfoPtrArray& aImplInfoArray);

public:

// Interface functions to be implemented by a concrete instance virtual void EncryptL(TDesC8& aPlaintext, TDesC8& aKey,

TDes8& aCiphertext, CryptoInterface::TAlgorithm) = 0;