<?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 task

  PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">

<task id="GUID-FF410602-8408-555E-B918-C0CF484535E7" xml:lang="en"><title>Writing

Interface Definitions</title><abstract><p>To use a plug-in, the client of the plug-in framework needs to

instantiate an object through the interface definition, use the object and

delete the object when the scope of the object usage is complete. Client calls

to the interface definition for construction and destruction translate directly

through REComSession into loading and unloading of the correct implementation. </p><p>The <xref href="GUID-9E0CBB66-A573-5BBE-9788-95B313325C7E.dita">interface definition</xref> defines

functions that offer services to the clients and enable object instantiation.

The object instantiation functions uses the plug-in framework to create an

instance of an appropriate implementation, and returns the instance to the

client. </p></abstract><prolog><metadata><keywords/></metadata></prolog><taskbody>

<context><p>A function in the interface definition delegates the object instantiation

to a static function <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-C7F147AC-6D77-3169-AAB4-B27262B4333B"><apiname>REComSession::CreateImplementationL()</apiname></xref> .

The <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-C7F147AC-6D77-3169-AAB4-B27262B4333B"><apiname>REComSession::CreateImplementationL()</apiname></xref> is an overloaded

function and offers many input parameter options. The appropriate <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-C7F147AC-6D77-3169-AAB4-B27262B4333B"><apiname>REComSession::CreateImplementationL()</apiname></xref> function

is called for object instantiation. If the client passes input data then this

data must be wrapped in a <codeph>TEComResolverParams</codeph> object. </p> <p> </p> </context>

<steps id="GUID-B502261A-48DA-5EC1-82F9-6136CF5A2C50">

<step id="GUID-D9F104A5-4D58-5488-AB0A-C90C26A40C28"><cmd>Derive an interface

definition class from <xref href="GUID-8F6FE089-E2A8-30F4-B67E-10F286347681.dita"><apiname>CBase</apiname></xref> or <xref href="GUID-727D2B62-09A9-3CBC-AB6F-591E52EC68EB.dita"><apiname>RHandleBase</apiname></xref> based

class. The class must always declare a private UID member. </cmd>

<info>The following shows an example segment of an interface definition class

that derives from CActive. </info>

<stepxmp><codeblock id="GUID-2D4E24B1-0463-5970-B0FD-321FC599E1CB" xml:space="preserve">class CExampleInterfaceDefinition : public CActive

    {

public:

    // Wraps ECom object instantiation

    static CExampleInterfaceDefinition* NewL();

     static CExampleInterfaceDefinition* NewL(const TDesC& aMatchString);

    // Wraps ECom object destruction 

    virtual ~CExampleInterfaceDefinition();

    // Interface service 

    virtual void DoMethodL() = 0;

...

private:

    // Instance identifier key or UID.

    TUid iDtor_ID_Key;

    };</codeblock> </stepxmp>

</step>

<step id="GUID-82F4FEE2-22B9-51E7-96CD-2CAA7FBF78C2"><cmd>Implement the object

creation function NewL() for the derived class. </cmd>

<info>Call the appropriate <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-C7F147AC-6D77-3169-AAB4-B27262B4333B"><apiname>REComSession::CreateImplementationL()</apiname></xref> function

if the implementation is to receive data from the client. </info>

<stepxmp><codeblock id="GUID-4447C35F-1001-57FB-941F-441E0A2C4799" xml:space="preserve">    // The NewL() function accepts client resolution string as input

inline CExampleInterfaceDefinition* CExampleInterfaceDefinition::NewL(const TDesC& aMatchString)

    {

    const TUid KExampleInterfaceDefinitionUid = {0x10009DC0};

    // The client resolution string is wrapped in TEComResolverParams object for resolution. 

             TEComResolverParams resolverParams; 

       resolverParams.SetDataType(aMatchString);

       TAny* ptr = REComSession::CreateImplementationL(

          KExampleInterfaceDefinitionUid,

         _FOFF(CExampleInterfaceDefinition,iDtor_ID_Key),

         resolverParams);

      return REINTERPRET_CAST <CExampleInterfaceDefinition*>(ptr);

      }</codeblock> </stepxmp>

<stepxmp><codeblock id="GUID-7F634037-2D79-53E0-B132-B9E963603B69" xml:space="preserve"/></stepxmp>

</step>

</steps>

<postreq><p>The interface definition needs to define a destructor function

to destroy the object after use. The interface destructor notifies the plug-in

framework about the object destruction. </p> <p>The destructor of the interface

definition must call the static function <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-8BA69111-0451-34CA-A1E8-C83513C4D29D"><apiname>REComSession::DestroyedImplementation()</apiname></xref> to

signal the object destruction to plug-in framework. The instance identifier

key is passed as a input parameter to <xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-8BA69111-0451-34CA-A1E8-C83513C4D29D"><apiname>REComSession::DestroyedImplementation()</apiname></xref> to

identify the instance. </p> <codeblock id="GUID-1E935BFD-D485-5F4D-9569-D34FEC1D90DC" xml:space="preserve">inline CExampleInterfaceDefinition::~CExampleInterfaceDefinition()

    {

    REComSession::DestroyedImplementation(iDtor_ID_Key);

}</codeblock> <p> <b>Note</b>: The memory clean-up function<xref href="GUID-1344F049-81C4-3D17-AF46-8B5584680ADB.dita#GUID-1344F049-81C4-3D17-AF46-8B5584680ADB/GUID-1AACEF53-2CAD-34EC-A485-CE49BC8B9BD8"><apiname>REComSession::FinalClose()</apiname></xref> should

not be invoked inside the destructor, or elsewhere in the interface. For more

details refer the topic <xref href="GUID-E3A80D62-09A5-502D-AB55-6AB2A5623465.dita">Cleaning-up

Memory</xref>. </p> </postreq>