Hemelix

Dynamic Link Library (DLL), an introduction

• Short for Dynamic Link Library, a library of executable functions or data that can be used by an application.
• A DLL provides one or more particular functions and a program accesses the functions by creating either a static or dynamic link to the DLL.
• A static link remains constant during program execution while a dynamic link is created by the program as needed.
• A DLL can be used by several applications at the same time. Some DLLs are provided with the operating systems and available for any application. Other DLLs are written for a particular application and are loaded with the application.
• A DLL must be loaded by an application, DLL is loaded in the memory area of loading process.
• Each DLL module can be developed independently and separately.

Static Linking DLL

• Static linking is the method used to combine the library routines with the application. When building the program, the linker will search all the libraries for the unresolved functions called in the program and if found, it will copy the corresponding object code from the library and append it to the executable.
• The linker will keep searching until there are no more unresolved function references.
• This is the most common method for linking libraries.
• This method boasts of ease of implementation and speed but will generate bulky executable.

Module Definition File

• static interface DLLs use an import library (lib) to obtain relevant information about exported functions.
• In conventional systems, DLLs may export by name or by ordinal. Symbian OS only supports exporting by ordinal.
  Exporting by ordinal reduces the time taken to find the item in the DLL export table and also reduces the size of the DLL as names need not be stored. Ordinals are used for accessing the address of a function in the DLL export table.
• It is only necessary to create def file for a polymorphic interface DLL, static interface DLLs use an import library to obtain relevant information about exported functions.

Dynamic Linking (Polymorphic) DLL

• In dynamic linking, the required functions are compiled and stored in a library normally with extension DLL.
• Unlike static linking, no object code is copied in to the executable from the libraries.
• In dynamic linking, the executable will keep the name of the DLL in which the required function resides. and when the executable is running , it will load the DLL and call the required functions from it.
• This method yields an executable with small footprint , but have to compromise on speed a little.

Polymorphic DLL

• A polymorphic DLL is one which is written to implement a programming interface defined elsewhere; for example, a device driver.
• The API is defined in terms of a single abstract class whose functions are declared as pure virtual. The DLL implements the API by defining and implementing a concrete class derived from that abstract class.
• The DLL exports a single function whose sole purpose is to create an object of the derived class type; this is always the function at ordinal 1 within the DLL.
  All other functions in the DLL are called through the virtual table mechanism (the pointer to the vtable is set up by the constructor in the normal C++ way).
• The user of a dynamically loaded DLL uses an RLibrary type object to load the DLL. The RLibrary object encapsulates a handle to the DLL and must remain in existence while the DLL is in use; typically this is for the life of the object provided by the DLL.

Create a static library step by step

In these steps we are going to create a static library and a client that will use this DLL. We pass a string from client module and that string will be printed to console by our DLL. For creating polymorphic DLL please take a look at the bottom how to create a Polymorphic DLL

• Create a folder like the following picture:




In Symbian this is convention that we use these folder. These folder are used for these purposes. There could be some other folders depending the project. But for simple project like we have these are enough. Even we can do our work without these files but this helps us to organizes codes in better way.

• group folder is used for keeping bld.inf (build information file) and mmp (make make project) files (there could be some other file depending on project)
• src folder are used for keeping source file (cpp files)
• inc folder are used for keeping header file (header and inline files)
• Create a file createstaticdll.h and copy this to inc folder.
• Contents of the file

#include <e32cons.h>
class CMessenger : public CBase
{
public:
/* Construction, client calls this methods and pass the console and the string to be printed
the will be displayed when ShowMessage() will be called on this object.
*param aConsole passed by client as reference
*param aString passed by client as reference and is stored in the dll
*return CMessenger type object to client and client is responsible for cleanup */
IMPORT_C static CMessenger* NewLC(CConsoleBase& aConsole, const TDesC& aString);
/* Destructor - virtual and class not intended
for derivation, so not exported
*/
~CMessenger();
/* general functions - exported this method will shows the string to the console
*/
IMPORT_C void ShowMessage();
private:
/* C++ constructor - not exported;
implicitly called from NewLC()
*/
CMessenger(CConsoleBase& aConsole);
// 2nd phase construction, called by NewLC()
void ConstructL(const TDesC& aString);
private:
/* Use the console (but not owned, this will be passed by reference from client)
*/
CConsoleBase& iConsole;
/* Allocated container for string data (destructor destroys)
*/
HBufC* iString;
};


• Create a file createstaticdll.cpp and copy this to src folder.
• Contents of the file

// CreateStaticDLL.cpp
// // This program creates a dll.

#include "createstaticdll.h"
#include <e32uid.h>

// construct/destruct

EXPORT_C CMessenger* CMessenger::NewLC(CConsoleBase& aConsole, const TDesC& aString)
{
CMessenger* self=new (ELeave) CMessenger(aConsole);
CleanupStack::PushL(self);
self->ConstructL(aString);
return self;
}

// destruct - virtual, so no export
CMessenger::~CMessenger()
{
delete iString;
}

EXPORT_C void CMessenger::ShowMessage()
{
_LIT(KFormat1,"%S\n");
iConsole.Printf(KFormat1, iString); // notify completion
}

// constructor support
// don't export these, because used
//only by functions in this DLL, eg our NewLC()
// first-phase C++ constructor
CMessenger::CMessenger(CConsoleBase& aConsole)
: iConsole(aConsole)
{
}

// second-phase constructor
void CMessenger::ConstructL(const TDesC& aString)
{
// copy given string into own descriptor
iString=aString.AllocL();
}


• Create a file named bld.inf file and copy that to group folder
• Contents of the file

// BLD.INF
// Component description file

PRJ_MMPFILES
createstaticdll.mmp


• Create a file named createstaticdll.mmp file and copy that to group folder


//
// Copyright (c) 2000-2005 Symbian Software Ltd. All rights reserved.

// using relative paths for sourcepath and user includes
// exports are unfrozen

TARGET CreateStaticDLL.lib // Note that extension is lib
TARGETTYPE LIB // Note that LIB is used
//UID2 and UID 3
UID 0x1000008d 0xE800004C
CAPABILITY NONE
// Vendor ID which company supply this SW
VENDORID 0x70000001

SOURCEPATH .
SOURCE CreateStaticDLL.cpp

USERINCLUDE .
SYSTEMINCLUDE \Epoc32\include

LIBRARY euser.lib


• Now you export this bld.inf file to your carbide tools and compile it. Check that you have a CreateStaticDLL.dll and CreateStaticDLL.lib in your epoc32\release\udeb folder
• Now we are ready to create our client module that will use this DLL
• Create a folder structure like the previous picture


• Create a file named bld.inf file and copy that to group folder
• Contents of bld.inf

// BLD.INF
// Component description file

PRJ_MMPFILES
usestaticdll.mmp


• Create a file named usestaticdll.mpp file and copy that to group folder
• Contents of usestaticdll.inf


// UseStaticDLL.mmp
//
/* Copyright (c) 2000 Symbian Ltd. All rights reserved.
*/

/* using relative paths for sourcepath and user includes
*/

TARGET UseStaticDLL.exe
TARGETTYPE exe
UID 0x0 0xE800004B
VENDORID 0x70000001
CAPABILITY NONE

/*
Following lines of code are used to create registration file. By this we can see the application icons in the application shell. */
SOURCEPATH ..\data
START RESOURCE usingstaticdlreg.rss
TARGETPATH \private\10003a3f\apps
END

SOURCEPATH ..\src
SOURCE UseStaticDLL.cpp

USERINCLUDE ..\inc
SYSTEMINCLUDE \Epoc32\include
LIBRARY euser.lib
/*Our library that we just created
STATICLIBRARY has been used to tell linker to insert code from the staticlibrary
*/
STATICLIBRARY CreateStaticDLL.lib


• Create a file named usingstaticdlreg.rss file and copy that to data folder
• Contents of usingstaticdlreg.rss

#include <appinfo.h>
UID2 KUidAppRegistrationResourceFile
// 3rd UID used in mmp file
UID3 0xE800004B

RESOURCE APP_REGISTRATION_INFO
{
// Name of the exe used in mmp file
app_file="UseStaticDLL";
}


• Create a file named usingstaticdlreg.rss file and copy that to data folder
• Contents of usingstaticdlreg.rss


// UseStaticDLL.cpp
//
// Copyright (c) 2000 Symbian Ltd. All rights reserved.

// standard example header
/* CommonFramework.h file contains the main function from where execution starts. There are some other common stuffs that has been used repeatedly in all examples */
#include "CommonFramework.h"
/*
This header file should come from the dll provider. In this case from our previous dll creation project. Best way to use this is include the path where this dll is located in your mmp file. For small test project we can directly copy this to our inc folder (like we have done here) */
#include "CreateStaticDLL.h"

_LIT(KTxt1,"statically linked DLL example \n\n");
_LIT(KTxt2,"Hello!");
_LIT(KTxtNewLine,"\n");

LOCAL_C void doExampleL()
{
console->Printf(KTxt1);
CMessenger* myMessage = CMessenger::NewLC(*console, KTxt2);
myMessage->ShowMessage();
console->Printf(KTxtNewLine);
CleanupStack::PopAndDestroy();
}

You could check that you have a CreateStaticDLL.lib file in your \epoc32\release\winscw\udeb. You can remove this file and noticed that your client application is still working. The reason for that is code from this lib has been inserted to the exe file.

Download area

Download source code

Download presentation material