<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-C7F3EDA1-B935-5F5F-AFD4-A3CABA0C031C" xml:lang="en"><title>Interface

Extensibility</title><shortdesc>Symbian^3 onwards, the plug-in framework supports

interface extensibility. An extended interface extends the existing functionality

of the original interface (instantiation interface). By extending interfaces,

the framework developers need not change the existing interface specifications

to support new requirements. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Framework developers who build the frameworks on top of the plug-in framework,

define and publish extension interfaces to the existing interfaces used in

the framework. Once an interface extension is published by the framework developer,

the plug-in developers implement the extensions if required. </p>

<section id="GUID-4BA2A6E9-9390-4B43-99BE-482A964D9785"><title>Introduction</title> <p>By extending interfaces, the framework

developers need not change their interface specifications to support new requirements. </p> <p>Changing

interface specifications is a complex activity in the below listed scenarios: </p> <ul>

<li id="GUID-BDEC7D4D-84A2-58C3-AE5A-06A418EC026A"><p>The framework developer

is not the only supplier of plug-in implementation. </p> </li>

<li id="GUID-26FB3ADE-C529-54A2-ACA9-26B06989A809"><p>The framework also needs

to support plug-ins implementing the original interface. </p> </li>

</ul> <p>The interface extensions allows framework developers to publish discrete,

identifiable extensions to the existing interface classes. The extension interfaces

supported by each plug-in can be determined and used appropriately. </p> <p>The

images below illustrate how the interface extensibility feature works. </p> <p>The

class diagram shows the implementation of the original interface. </p> <fig id="GUID-C85FB42D-1EE5-508E-B81F-D96B8A8E23E7">

<title>              Class diagram of the original interface            </title>

<image href="GUID-7D78DFA8-301C-5A0C-9F83-7C4BBEAE34C2_d0e218556_href.jpg" placement="inline"/>

</fig> <p>The next class diagram shows an example of the original class <b>CImplementationClass</b> supporting

two extensions . The extensions have been added to the <b>CExampleInterface</b> each

using a different implementation methodology . </p> <p> <b>CExampleInterfaceExtended</b> requires

no data and so has been added to the inheritance of the original plug-in <b>CImplementationClass</b> object. <b>MExampleInterfaceExtended2</b> shows

how extensions can be realized in separate objects with their own data. </p> <fig id="GUID-B2D1AF5C-0789-5D9B-8EB1-13226C864D38">

<title>              Class diagram of the extended interface            </title>

<image href="GUID-DAF12BDB-5453-5DDD-ACBA-4C29AE448D87_d0e218585_href.jpg" placement="inline"/>

</fig> <p>The extended interfaces should maintain the binary compatibility

by not changing the original interface class definition. The functional compatibility

should be maintained by incorporating interface extensions as optional. This

allows the framework to function with original and extended plug-in implementations. </p> <p>To

accommodate interface extensibility, the following changes are applied to

the plug-in framework. </p> <ul>

<li id="GUID-6D8129A2-4829-5039-AAAE-FB6529CC6F56"><p>A new resource file

format to allow plug-in providers to register interface with extensions (Resource

file format version 3). </p> </li>

<li id="GUID-9F6DF121-3B7F-54AC-88A1-3DBFA428FCDA"><p>A new <codeph>targettype</codeph> PLUGIN3. </p> </li>

<li id="GUID-615B9514-77A7-505B-82C5-B71EFEE4C80E"><p>New APIs accommodated

in the framework to search for plug-ins supporting desired interface extensions. </p> </li>

<li id="GUID-C7C6CED9-18A8-5C28-98B6-C8061EC73DFC"><p>A new proxy table for

the plug-in implementations to export factory methods to instantiate the extended

interface objects and a method to manually release the objects after use. </p> </li>

</ul> <p>Accommodation of interface extensibility still allows the default

resolvers and custom resolution of implementations. </p> </section>

<example><title>Interface extensibility example</title> <p>The code below

shows the definition of an extended class: </p> <codeblock id="GUID-C0A7CEC3-5078-5482-8483-0CE338077DD5" xml:space="preserve">

class CExampleInterface : public CBase

{

public:

    virtual void DoMethodL() = 0;

};

// Extended Interface 0x10009E44

class MExampleInterfaceExtended

{

public:

    virtual void DoMethodExtended() = 0;

};

// Extended Interface 0x10009E45

class MExampleInterfaceExtended2

{

public:

    virtual void DoMethodExtended2() = 0;

};

</codeblock> <p>The code below shows the instantiation of extended functions: </p> <codeblock id="GUID-AF382EE0-C8D0-55ED-807A-2A51C3D8B72A" xml:space="preserve">// the Instantiation Interface

const TUid KExampleInterfaceUid = {0x10009DBB}; 

const TUid KExtendedInterfaceUid1 = {0x10009E44};

const TUid KExtendedInterfaceUid2 = {0x10009E45};

// Set up extended interfaces UID list which form part of the resolution criteria.

RArray<TUid> extendedInterfaces;

CleanupClosePushL(extendedInterfaces);

extendedInterfaces.AppendL(KExtendedInterfaceUid1);

extendedInterfaces.AppendL(KExtendedInterfaceUid2);

// set up resolve parameter

_LIT8 (KExampleImplementationData,"Extended Interface Example");

TEComResolverParams ResolverParams;

ResolverParams.SetDataType(KExampleImplementationData());

ResolverParams.SetGenericMatch(ETrue);

TUid instanceKey;

CExampleInterface* instantiateIf = static_cast<CExampleInterface*>

(REComSession::CreateImplementationL(KExampleInterfaceUid,

                                       extendedInterfaces,

                                       instanceKey,

                                       ResolverParams) );

CleanupStack::PopAndDestroy(&extendedInterfaces);

CleanupStack::PushL(instantiateIf);

// May want to TRAP here if KErrNotSupported is handled, i.e. extension optional

MExampleInterfaceExtended2* ext2 = static_cast<MExampleInterfaceExtended2*>(

  REComSession::GetExtendedInterfaceL(instanceKey, KExtendedInterfaceUid2));

// access old interface function

instantiateIf->DoMethodL(); 

// access extension function 

ext2->DoMethodExtended2();   

</codeblock> </example>

</conbody></concept>