<?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-301193C2-666C-5A57-B898-A04EBB63E533" xml:lang="en"><title>How to

use a polymorphic interface DLL</title><shortdesc>The example issues a greeting to the person whose name is passed

in the descriptor <codeph>aName</codeph>.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The following code can use any implementation of the interface defined

by the example class, <codeph>CMessenger</codeph>, to issue a simple greeting.</p>

<p> The name of the DLL, which contains the implementation to be used, is

passed in the descriptor <codeph>aLibraryName</codeph>.</p>

<codeblock id="GUID-3BBCFE9F-7D77-563A-AE87-4BBE2B7F195E" xml:space="preserve">void UseDllL(const TFileName&amp; aLibraryName,const TDesC&amp; aName)

    {

          // Use RLibrary object to interface to the DLL

    RLibrary library;

          // Dynamically load the DLL

    TUidType uidType(KDynamicLibraryUid,KMessengerUid);

    User::LeaveIfError(library.Load(aLibraryName,uidType));

          // Function at ordinal 1 creates new CMessenger

    TLibraryFunction entry=library.Lookup(1);

          // Call the function to create new CMessenger

    CMessenger* messenger=(CMessenger*) entry();

          // Push pointer to CMessenger onto the cleanup stack

    CleanupStack::PushL(messenger);

          // Second-phase constructor for CMessenger

    messenger->ConstructL(console, aName);

          // Use Cmessenger object to issue greeting

    messenger->ShowMessage();

          // Pop CMessenger object off cleanup stack and destroy

    CleanupStack::PopAndDestroy();

          // Finished with the DLL

    library.Close();

    }</codeblock>

<section id="GUID-738C30CA-1A75-4038-8BB4-68682D3C539C"><title>Notes:</title> <ul>

<li id="GUID-01B13D4C-7028-5987-B993-213E6FE9E571"><p>the <codeph>RLibrary</codeph> class

is the interface to dynamically loaded DLLs. It encapsulates a handle to the

DLL.</p> </li>

<li id="GUID-726B2AA5-7674-5DA1-B6FA-EB10F85D7D1F"><p>The DLL has a <codeph>TUidType</codeph> which

is assigned when the DLL is built. This is ensures that the DLL that is loaded

complies with the <codeph>CMessenger</codeph> protocol.</p> </li>

<li id="GUID-F5F2DAE3-62B2-5690-92FF-85AF3F8C987F"><p>If a specific implementation

of the DLL is to be used, then specify a third UID when declaring the TUidType.

Each specific implementation of the DLL is uniquely identified by the third

UID.</p> </li>

<li id="GUID-C24783C0-CCFA-5AF1-9941-7FB5D0504756"><p>A pointer to the ordinal

1 function in the DLL is fetched by calling the <codeph>Lookup()</codeph> member

function of <codeph>RLibrary</codeph> and passing it a parameter value of

1. The returned function has type <codeph>TLibraryFunction</codeph>; such

a function takes no parameters and returns a <codeph>TAny*</codeph> type.</p> </li>

<li id="GUID-C1FB1A45-A02A-5B10-B1EA-AE84982DB6BC"><p>The function pointer

is assigned to the variable called <codeph>entry</codeph> and the function

itself is called to construct a <codeph>CMessenger</codeph> object and return

a pointer to that object. The implementation uses the <codeph>new (ELeave)</codeph> operator

to allocate the new <codeph>CMessenger</codeph> object and invoke the C++

default constructor.</p> </li>

<li id="GUID-1A7CBF75-9059-5AED-ABA9-DF649D613988"><p>As no arguments are

passed to the function, a second-phase constructor, <codeph>ContructL()</codeph>,

is called to finish off construction.</p> </li>

<li id="GUID-B58DFA44-368F-578B-B35D-7DBF1C67A83A"><p>The <codeph>CMessenger</codeph> object

can then be used like any other C++ object. In this example, the <codeph>ShowMessage()</codeph> function

is used to emit a greeting in whatever way the implementation chooses. In

more complex cases, the object could have a long lifetime, and create many

dependent objects.</p> </li>

<li id="GUID-67D8B0AA-8425-52C1-851A-D022B7847448"><p>When the <codeph>CMessenger</codeph> object

is no longer needed, the DLL is unloaded using <codeph>RLibrary::Close()</codeph>.

Do not call any code in the DLL after the library has been closed. It is important

to note, therefore, that the library must not be closed until the object constructed

by the DLL, <i>and all its dependent objects</i>, have been destroyed.</p> </li>

</ul> </section>

</conbody></concept>