DLL Template which lets your project take off

• Download source files - 21 Kb

Introduction

Often reusable code is stored in DLL form. Not just you but your colleagues and your clients are expected to use it. Thus its is not only functionality that matters but also the documentation. I will touch both aspects of this while comingup with a template that serves general DLL writing. What I will discuss is not the internal working of DLL. You can find this in any VC++ development book. I assume that user knows the basics of DLL such as feature export/import, compiling, linking, c++.

1.    Functionality 
     a. Export/Import key word:
Most of the time while authoring a DLL we do not keep the user in mind.  Our intention is to export the features in the DLL. In that process  we tend to hardcode the key words __declspec(dllexport) or  AFX_CLASS_EXPORT as the case may be. 

Example: 
Content of FileLog.h

....
__declspec(dllexport)  BOOL LogToFile(const char* logFile, const CString string);
....

User would include this header file in his code and link his executable  with your library. But when user does this, function LogToFile() is  even now EXPORTED !!! He should have been importing it. You then say  I will give him a separate header file which is an exact replica of FileLog.h but has __declspec(dllimport) in it. This way both of us are  happy. 
Content of user FileLog.h

....
__declspec(dllimport)  BOOL LogToFile(const char* logFile, const CString string);
....

But this is just one function and one header file written just by you. Tomorrow this DLL might have tens of functions and classes in hundreds  of files authored by many users. Can you maintain two copies of the same header file ?? Even if you think ‘may be’, say NO.

Problem can be solved very easily. By using something called  onditional compilation. Macros. All of us would have used it in one form or the other. What you do is define a macros which will expand to __declspec(dllexport) at the programmer end and __declspec(dllimport) at the user end. This is how you do it. 

#ifdef MYLIB_API
    // All function in this file are exported
#else  // MYLIB_API <br>
    // All function in this file are imported 
    #define MYLIB_API __declspec(dllimport)
#endif // MYLIB_API

I can do something similar for classes too 

#ifdef MYLIB_CLASS
    // All function in this file are exported
#else  // MYLIB_CLASS
    // All function in this file are imported
    #define MYLIB_CLASS AFX_CLASS_IMPORT
#endif // MYLIB_CLASS

You can find this in  DLLHeader.h. What you also need to do is define MYLIB_API and MYLIB_CLASS in your implementation (.cpp)before you include the respective header file.
Example. Content of FileLog.cpp 
 
....
// This dll source file exports functions and variables. 
// Must be present in all impl files before #include of respective header files.
#define MYLIB_API __declspec(dllexport)
#define MYLIB_CLASS AFX_CLASS_EXPORT

#include "FileLog.h"
....

Isn’t this simple ? You can make this part of your DLL implementaion file-template. 

b.Organization:
Biggest problem I have faced in DLL development is its maintenance. You need to be disciplined right from the beginning. Make sure you and all authors of the DLL follow strict coding standards, appropriate documentation, templates that I discussed. 

Besides these you also need to make sure that you don’t overload your functionality in a single header/implementation. What I mean is even if there are closely related functionality which differ by their technology put them in separate files. For example you have written two sets of features which does the same, say, voice recording and replay. One uses MCI and the other uses PSAPI technology. Even though they are functionally similar, put them in different header and implementation files. You are doing this simply because tomorrow you will add more features into them, say pause, format conversion,..  It would be very expensive to make changes then.

Organization is not just at the file level. You also need to organize code within your files too. C++ provides a very nice way of doing this using ‘namespace’. Always mark your segment of code within and across files as belonging to one  particular ‘namespace’. This will help the ser clearly spot his choice of  feature. For example if you have written two  variants of a function you can put them in two different namespace and retain the same name for both the function.

c.Log 
While Debugging a DLL you cannot rely much on the debugger.  Many books make debugging look very simple. You can set the executable path in the Debug tab of Project Setting to the application which loads your DLL, and  then debug your DLL. This is a simple scenario. But there are cases where your DLL might be loaded by an application which is loaded by a third party application which is invoked by  your application. For example Browser Helper Objects(BHO) are in-proc DLL which are loaded by Internet Explorer.  If you want to write a tracker application you need to  write the BHO as well. In such cases it might not be  possible to load your DLL (BHO) in the debugger. The way  I do it is using log files. So at times you need to think about logging mechanisms for your DLLs too.

2.Documentation
Your DLL needs to be documented more than any of your executable. This is because they DLL’s have wider stake holders. Just handing over a API manual might just not  be sufficient. You need to document use-cases, exceptions in code form in your DLL. I have a file named Usage.txt which gives code on how to use my DLL. Whenever I add a feature to the DLL, I make sure it is reflected in the Usage.txt file. You can place this file in the same level as your source and header folders. Note that I capture not just the application of my feature, but also the code  surrounding the application.

Code
I have created the DLL using MFC wizard. It is a regular DLL with MFC statically linked. The exports in the DLL may not do anything useful, but it gives you the gist of DLL layout. Once you put the layout in place you can keep adding more features (function and functions) into it and be sure that your client is happy with the it both in terms of functionality and documentation.