A Short Tutorial on Writing a DLL

Glenn D. Jones
November 8,1995
Introduction
This tutorial will explain the basics of writing a Windows DLL. I will direct i
t at Visual Basic programmers who have decided they need to write a DLL for thei
r VB applications. However, VB programmers not are the only users of DLLs. Tho
se programmers who want to write a DLL to interface with other languages will al
so find this tutorial useful.
In addition this tutorial is specific to writing a DLL using C.
What is a Dynamic Link Library?
A Dynamic Link Library, DLL, is a library of functions callable by an applicatio
n at runtime. The application and functions within the DLL are not bound until t
he application program is executed.
Normally the functions in a DLL are for a particular purpose (internet access, g
raphing, serial port communication). They may also be a collection of functions
required by an application and only be specific to that application. This is o
nly convention, if you are writing a DLL you can put whatever functions you want
into it.
If you are going to write and distribute a DLL, you do not need to register its
name nor get an ID from anyone. You can name it whatever you want, but please t
ry to make it unique. If you call your DLL "KERNEL.DLL" you will have problems
with it (KERNEL is a Microsoft Windows DLL used to perform operating system kern
el functions).
An application can bind to a DLL in two ways:
Load Time Binding
On Call Binding
Load Time Binding loads the DLL when an application that uses it is loaded for e
xecution. Windows loads the DLL for the application.
With On Call Binding, the DLL is loaded when it is needed. If it is never neede
d by the application it will never be loaded.

Visual Basic loads DLLs when the form that contains their Declare statement is l
oaded. If a VB application places the DLL function declare in a module or on a
form that is loaded when the application is loaded, then the DLL will be bound a
t application load time. If the declare is placed in a form that is dynamically
loaded by the VB application, then the DLL will be loaded when the form is load
ed.
One last note on loading DLL's, Windows will locate a DLL in the following order
:
In memory, a DLL, once loaded, is global to all of Windows until it is unloaded.
In the directory where the application was loaded from
In the windows directory
In the windows\system directory
In directories specified in the DOS PATH

What do I need to write a DLL?

As of today, most DLL's are written in C. It is possible to write a DLL in PASC
AL/Delphi or assembly language. (There was a product on the market that allowed
DLL's to be written in Basic but I have not seen mention of it for while. If an
yone knows of this, please let me know.)
In order to write a DLL you will need a compiler capable of creating Windows DLL
. The four most popular C compilers that can do this are:
Microsoft Visual C++
Borland C++ for Windows
Symantec C++ for Windows
Watcom C++
If you do not have a compiler, you will need one to write a DLLs.
In addition to the compiler, you will need knowledge of C and the Windows API.
NOTE: C is the language that is used to write a DLL, not C++. C++ is an object
oriented extension of C. If you have a C++ compiler, it can handle C just fine.
You can also write non-exported functions as C++ objects, but the functions th
at are called into from Windows applications must be C functions, not C++ functi
ons or methods.
DLL Requirements
A Windows DLL requires only one function called LibMain. If a DLL does not have
a LibMain it will not work.
Windows calls the LibMain function of a DLL to initialize the DLL. For most sim
ple DLL's, you code LibMain as follows:
int FAR PASCAL _export LibMain(HANDLE hInstance,WORD wDataSeg,
WORD wHeapSize,LPSTR lpszCmdLine)
{
if(wHeapSize > 0)
UnlockData(0);
return(1);
}
You can find details of LibMain in the Windows API documentation.
The only other requirement of functions in a DLL is that those functions that c
an be called from outside the DLL, must be declared "FAR PASCAL _export". If yo
u do not declare them this way, you will not be able to call them.
You will also need a special DEF file for a DLL. Below is a sample that was gen
erated by Microsoft Visual C++. Most of today's compilers will generate the DEF
for you, but if yours does not, create one that looks like this:
LIBRARY <your DLL name goes here>
EXETYPE WINDOWS
CODE PRELOAD MOVEABLE DISCARDABLE
DATA PRELOAD MOVEABLE SINGLE
HEAPSIZE 1024
EXPORTS
WEP PRIVATE
; To implement your own Windows Exit Procedure add the following
; function to your application (referring to it in the .def file is
; not required.) The extern "C" is only required if module is C++.
; extern "C" int FAR PASCAL _WEP(int)
; {
; /* Your WEP functionality goes here */
; return 1;
; }
That is it. After you compile and link, you can begin testing your DLL.
The samples that go with this tutorial contain all of this basic information. Y
ou can use it as a template to start writing your first DLL.
What can I do in a DLL?
Many people ask what is permissible in a DLL. Well, just about anything is perm
issible. When an application calls a DLL function, the DLL is executing as an e
xtension of the application's task. Any files it opens are open to the task; an
y memory allocated is allocated from the task's local or global heaps. Just kee
p this in mind and you will be fine.
Let's look at a small example. If you write a DLL that executes a LocalAlloc AP
I call for 32000 bytes and it does not call a LocalFree on that memory handle be
fore returning, the DLL will have just taken 32000 bytes of the applications loc
al heap. You will probably start getting out of memory messages from the applic
ation.
Some of the things you might want to do in a DLL are:
Make GDI function calls to paint the screen.
Allocate Windows global memory
Perform file I/O
Search Windows internal tables
Perform port I/O
Call other API's
All of these things are possible, the most important thing to remember is to wri
te your DLL as clean as possible. If you allocate a resource, and you do not ne
ed to keep it, free it before you return from your DLL function. Always remembe
r, a DLL can cause all kinds of problems in Windows and they might not show unti
l your DLL has long been unloaded.
Also remember that a DLL is global. If you store data in a global variable insi
de a DLL and two tasks are currently using the DLL, they will both be accessing
the same global area in the DLL. In addition, when Windows unloads the DLL, you
lose the global data.
BE CAREFUL AND KEEP IT CLEAN.

Where can I get sample DLL source?

You can find source code for DLL's on almost any Internet FTP site dealing with
Windows programming as well as other on-line service forums. The problem with m
ost of this source is that the DLL was written for a purpose. You have to wade
through hundreds of lines of code just to get an idea of what you need for a sim
ple DLL.
Included with this tutorial is a sample DLL that does nothing but add two argume
nts and return the result. It contains the source code and project files for bo
th Borland C++ and Microsoft Visual C++. In addition it contains a VB program,
with source, that calls the DLL.
If there is a demand for more complicated DLL's (maybe some showing how to perfo
rm GDI calls or access VBX control information) I could probably be persuaded to
add more samples to this tutorial. Let me know.
Where can I get more information on writing a DLL?
Most good books on C programming for Windows will include a chapter or two on wr
iting a DLL. Browse your local book store and find one you like.
Since writing a DLL is really just writing a Windows program, you will need acce
ss to the Windows API documentation. You will also want to get information on w
riting programs using GDI, KERNEL and other part of Windows.
About the author
I, Glenn Jones, have been a professional programmer for 16 years. For most of t
his time I have been designing, writing and supporting system software (compiler
s, debuggers, code generators, communication API's ect). I have worked in a var
iety of environments and with many different languages and compilers. At this p
oint I am dedicated to describing and helping programmers with the debugging pro
cess. I believe that the first step in debugging a program is understanding the
principles of the environment for which you are writing. If you need to write
and debug a DLL, then you need to know how to write a DLL correctly.
If you have any questions or comments about this tutorial or suggestions for fut
ure tutorials, please contact me at gdjones@ix.netcom.com.
Have fun.
Copyright and Distribution
This document is Copyright ( 1995 by Glenn D. Jones. It may be distributed free
ly for non-commercial use. It may not be included in print or electronically pu
blished for sale without the permission of the author.
Microsoft Visual C++, Microsoft Visual Basican Windows are copyright Microsoft C
orporation.
Borland C++ is copyright Borland International, Inc.