<?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-&gt;ConstructL(console, aName);
          // Use Cmessenger object to issue greeting
    messenger-&gt;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>