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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

    12 <concept id="GUID-260C7ACD-0024-59DE-B1C6-0C852E44C457" xml:lang="en"><title>Dynamically

    13 Loading Link Libraries Overview</title><shortdesc>Description of Polymorphic DLLs.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    14 <section id="GUID-25D3E357-BE6E-40BD-897D-DA5EB92029C5"><title>Purpose</title> <p>Dynamically load libraries during program

    15 execution.</p> <p>These interfaces are used by programs that need to load

    16 libraries at run-time, that have a common interface, but different concrete

    17 behaviour. Because of this relationship between interface and behaviour, such

    18 libraries are called <i>polymorphic DLLs</i>. </p> </section>

    19 <section id="GUID-5444CFD3-5FC2-4160-BD8A-8BD7154402B3"><title>Architectural relationships</title> <p>Many parts of the system

    20 use polymorphic DLLs. Communications components, such as Sockets and Messaging,

    21 use architectures in which particular communications protocols are provided

    22 as polymorphic DLLs, and are loaded as needed. UI application programs are

    23 also polymorphic DLLs that are loaded when the user starts the program.</p> </section>

    24 <section id="GUID-2A379537-7B05-445F-83FC-C4396794A3CD"><title>Description</title> <p>The API has three key concepts: polymorphic

    25 DLL, polymorphic DLL handle, and polymorphic DLL function pointer. </p> </section>

    26 <section id="GUID-0A0DF81E-94C0-4D91-8F2A-1DFBE542E019"><title>Polymorphic DLL</title> <p>A program that uses a type of polymorphic

    27 DLLs defines their interface in terms of a single abstract class whose functions

    28 are declared as pure virtual. Each type of polymorphic DLL is given a unique

    29 identifier (UID). </p> <p>A particular concrete DLL:</p> <ul>

    30 <li id="GUID-E073605D-1AC4-55B9-94AA-FD1A761B5448"><p>implements the interface

    31 by defining and implementing a concrete class derived from the abstract class.</p> </li>

    32 <li id="GUID-AF95C27B-841D-53B5-836B-A55B4ED3E5F3"><p>exports a function that

    33 creates an object of the derived class type. All other functions in the DLL

    34 are virtual and called through the base class interface.</p> </li>

    35 </ul></section>

    36 <section id="GUID-825B7916-7E13-42B5-BAE4-A7009679E4F2"><title>Polymorphic DLL handle</title><p>The polymorphic DLL handle

    37 allows a program to load and close a particular polymorphic DLL. It also allows

    38 the caller to obtain pointers to functions exported by the DLL. The system

    39 can check that a polymorphic DLL is of the correct type by checking the type

    40 UID value.</p> <p>The polymorphic DLL handle interface is provided by <xref href="GUID-25327159-83D6-3507-B187-09EA4BB3727F.dita"><apiname>RLibrary</apiname></xref>.</p> <p>A

    41 wildcard file system search for polymorphic DLLs can be done through <xref href="GUID-1B05E2E3-B64E-36A8-BFFF-430028113BA4.dita"><apiname>TFindLibrary</apiname></xref>.</p> </section>

    42 <section id="GUID-C16BECEC-B59A-4FFE-94F0-548DB602A0BA"><title>Polymorphic DLL function pointer</title> <p>An exported function

    43 is called through a pointer to function obtained through a polymorphic DLL

    44 handle.</p> <p>The polymorphic DLL function pointer type is provided by the <xref href="GUID-7E0A7BA7-0EF8-3832-A1EA-B85FFADD1A9B.dita"><apiname>TLibraryFunction</apiname></xref> typedef.

    45 The caller casts the pointer to the real type of the exported function before

    46 using it.</p> </section>

    47 </conbody><related-links>

    48 <link>

    49 <desc><xref href="GUID-AB705D21-87A3-5F32-A4B9-17B7593DD5C3.dita">UID Manipulation

    50 Overview</xref></desc>

    51 </link>

    52 </related-links></concept>