Writing a DLL

Tutorial posted September 4th, 2003 by eric
in

A DLL (Dynamic Link Library) is a piece of code (a library) that is linked to a program at runtime rather than during the build process. The code inside a DLL can be shared by several clients at the same time without being duplicated in the mobile memory.

Static Interface vs Polymorphic Interface

Symbian OS supports two types of DLLs :
-  Static Interface DLL
-  Polymorphic Interface DLL

A static interface DLL is automatically loaded in the mobile RAM memory when a program that use it is started (except if it is in ROM where it is executed in place). It is also automatically unloaded when nobody needs it anymore. The static interface DLL provides a unique set of function within the system (i.e. two DLLs with the same exported function could not coexist in the system). Static interface DLLs have .dll file extension and are commonly used to implements application engines (i.e. UI independent code) in Symbian OS.

A polymorphic interface DLL is loaded explicitly by calling RLibrary::Load() and shall be unloaded using RLibrary::Close(). Several polymorphic DLLs can expose the same interface to their clients. So this kind of DLLs is generally used by a framework to provide plug-ins facility. Polymorphic Interface DLLs can have several different file extensions in Symbian OS. The most known one being .app (applications), .ldd (logical device drivers, .tsy and .csy (telephony and communication server modules),...

We will only focus on static interface DLLs which is the most common type of DLLs you (and I!) have to write. We will use the generic DLL term in the rest of the article.

A Static Interface DLL

From a client point of view, a DLL is made of three files:
-  a header file, which as .h file extension and which is #included by the client and needed at compilation time.
-  a import library file (.lib file extension) which the client links againts. This file contains the interface provided by the DLL.
-  the DLL itself (.dll file extension) which contain the implementation of all functions of the DLL and an export table so that the link can be completed at execution time.

From the provider point a view, the DLL can be seen as a complete Symbian project. It shall have:
-  its own MMP file (listed in a bld.inf file)
-  a header file that specifies the interface
-  source code file(s) that contain the implementation.

The header file

A DLL header file is very similar to other classes header files. The important thing to remember is to use the IMPORT_C macro in the declarations of all functions to be exported:

class CMyEngine : public CBase
{
public:
   // These functions are visible by the
   // clients of the DLL and needs to have
   // the IMPORT_C tag
   IMPORT_C static CMyEngine* NewL();
   IMPORT_C static CMyEngine* NewLC();

   IMPORT_C void MyPublicMethod();
   IMPORT_C void AnotherPublicMethod();
   ...
private:
   // These functions are not visible by the
   // clients of the DLL and then do not need
   // the IMPORT_C tag
   CMyEngine();
   void ConstructL();
   void SomePrivateMethod();
}

The implementation file

Writing a DLL has not many impact on code in itself. But there are two important points to respect:
-  an implementation for the E32Dll() function shall be provided (see code below).
-  another specific macro, EXPORT_C, should be added in front of each exported function implementation. :

// This function is mandatory for all DLLs
EXPORT_C TInt E32Dll(TDllReason)
{
        return KErrNone;
}

// This function is exported: The EXPORT_C tag shall be used.
EXPORT_C void MyPublicMethod()
{
   ...
}

// This one is not: The EXPORT_C tag shall not be used.
void SomePrivateMethod()
{
  // Do Something
}

The MMP file

The MMP file for the DLL should:
-  define the project's target type as dll
-  use the appropriate UID2 value (0x1000008d)

During development phasesn, you should also tell the build environment that DLL interface is not finalised by using the EXPORTUNFROZEN primitive:

TARGET        MyEngine.dll
TARGETTYPE    dll
UID           0x1000008d <myUID3>
...
EXPORTUNFROZEN

Freezing the DLL interface

Once you have finished your development, and before releasing versions of your DLL, you should freeze the interface, so as to ensure the backward compatibility of future releases of a library.

To do this, remove the exportunfrozen keyword from your MMP file and build the project in the normal way: a warning will be generated to the effect that the frozen .def file does not yet exist. Once the project has been built you can freeze by using:

abld freeze

Note that all ARM platforms share a common .def file, but that WINS/WINSCW has a different .def file.

Once the project is frozen, regenerate the makefiles so that the import library will be created directly from the frozen .def file.


> Writing a DLL

On October 7th, 2003 Anonymous said:
If I would want to write an Polymorphic DLL such as Logical Device Driver, what should I need to know?

> Writing a DLL

On October 7th, 2003 eric (not verified) said:
You should get in touch with Symbian to get the proper development kit. You cannot develop a device driver using public SDK. It's also a good idea to follow the "OS Internals" training course.

> Writing a DLL

On February 11th, 2004 Anonymous said:

Hi,

I am linking gsoap library into my app. For some reason, when I loaded the app on the actual target (nokia 3650), I got system error.

What's weird is that when I loaded the sample app that came with gsoap, the sample app loaded fine on my phone.

Do you know why this happening? I desperately need to solve this problem.

Thanks in advance for your help.

Basari

> Writing a DLL

On April 7th, 2004 Hannu (not verified) said:
Is your gsoap library also on your device? System error in application start often means that some DLL is missing.

> Writing a DLL

On October 24th, 2003 Anonymous said:
Hi, you mention the UID2 must be 0x1000008d for dlls. Howcome? What are the other UID2 values, like for apps? And also - do theses values change between the symbian versions? BR

> Writing a DLL

On January 8th, 2004 isawit (not verified) said:
to see the list of uid just visit : http://www.symbian.com/developer/techlib/v70docs/SDL_v7.0/doc_source/ToolsAndUtilities/BuildTools/build-dll/polyUID.html

> Writing a DLL

On March 24th, 2004 SergioEstevao (not verified) said:

Hi

After i have create my dll how can i use in another project?

And to copy and use it in the mobile device?

Sergio

> Writing a DLL

On March 29th, 2004 Mourad (not verified) said:
hey Sergio we have the same problem, so whenever u know the solution, please send me a mail containing the solution, and thanks :)

> Writing a DLL

On May 26th, 2005 White Junior Dragoon (not verified) said:
Hey guys, to properly use it you should copy the.dll file in : system\\libs and have fun!!!

> Writing a DLL

On September 27th, 2004 Anonymous said:

I am writing a static dll and I keep getting weird errors. I have the following line in my dll code. [code] EXPORT_C TInt E32Dll(TDllReason)return KErrNone;

When I like the applicaiton code with the dll i get the following error message;

Could Not Find C:\Symbian\7.0s\Series60_v21\EPOC32\BUILD\SYMBIAN\7.0S\SERIES60_V 21\TEST\GROUP\TEST\WINS\UDEB\TEST.exp NMAKE : fatal error U1077: 'del' : return code '0x1' Stop. make: *** [TARGETTEST] Error 2

why am I getting this error and how do I correct it? This is how I build the applicaiton;

abld build wins udeb

Please help me

> Writing a DLL

On December 3rd, 2004 Anonymous said:

Hi,

It seems to me that you are actually writing a polymorphic DLL that should export just a single function at ordinal 1. This is generally done by writing an extern function (to avoid name mangling done by C++ compiler).

If you wanna write a plolymorphic DLL, and if you write the DLL entry point for it with TInt E32Dll(), then, when you do abld build, the linker will typically give you the above error.

Please replace the E32Dll() with proper entry point function, and things should work for you.

I had similar problems when I was writing a .PRT module and then again when I was writing one .FSY module. :-)

Hope that helps.

 Viren

> Writing a DLL

On June 7th, 2005 Anonymous said:

Hello Viren,

I am trying to write a .prt I still could not find any sample. If you don't mind can I take a look at your code??

Best, Burge

> Writing a DLL

On October 19th, 2004 Anonymous said:
I encountered a problem when compiling a dll project for the very first time: everything went well, except for the fact, that the resulting dll file wasn't created at all. Later, I figured out that Symbian SDK doesn't create dlls of 'empty' dll projects( projects, that yet don't have any IMPORT_C and EXPORT_C statements in the source code). Am I right.. or is there any other explanation to this feature?

> Writing a DLL

On April 21st, 2005 dinesh verma (not verified) said:

Hi

I have made my own static Dll .Its both .dll and .lib files are with me.

Can anyone tell me how to use it in other applications.

> Writing a DLL

On July 4th, 2005 Anonymous said:

i'm new in symbian but i think that you are asking for this

add to the mmp file of the new application, the line with your library

inside mmp: LIBRARY YOURLIBRARY.LIB

remember to put the include for the dll in the pkg file when you wanna make your sis file

i hope this can helps you

12next ›last »