A simple plug-in architecture pattern for C++ applications on
Win32
By George Mihaescu
Summary: This article presents a simple and elegant
solution to creating components that can be dynamically deployed and loaded by
a C++ Win32 application without the need of any framework / infrastructure or
technology (such as COM). It relies on basic C++ mechanisms and two commonly
used Win32 API calls.
Download the code here
(VC++ projects + source).
The Problem
You have a C++ Win32 application to which you want to be
able to “attach” components dynamically, developed either by yourself or by
other parties. In the context of this document I will call those components
plug-ins, by analogy with the well-known web browser add-on components. In the
same manner with the browsers, you want your application to be aware of such plug-ins
that were developed and deployed possibly long after the application itself was
developed and deployed. Ideally, you don’t want the application to even need to
restarted – what you’d like is to drop the plug-in at a know location (e.g.
somewhere under the application installation directory) even as the application
is running, and the application all of a sudden has enhanced functionality. Can
this be done in a simple and reliable way?
The Solution
Many readers will immediately dismiss the problem and this article
by saying “of course, that’s what COM is all about”. But I’m not in favor of
using COM unless there is a very compelling reason for it. Generally, if it can
be done without COM (without making the code overly complex – I don’t want to
re-implement COM), then why bother with COM? Say COM and you say code
complexity, registration issues (such as registration requiring certain user
security privileges), dependency on registry, application usually needing to be
re-started, etc. I argue below that I can meet the requirements of this problem
without COM, in a much simpler and reliable way.
High-level design
My solution is based on marrying the C++ polymorphic
mechanism with the Win32 APIs LoadLibrary and GetProcAddress.
The principle is that the main application publishes a
contract with the plug-ins in the form of an interface that the plug-ins are
expected to implement in order to meet the contract. Then the main application
will scan a known location on disk (e.g. a “plugins” directory relative to its installation
directory) and attempt to load all plug-ins (using LoadLibrary API) that
export implementations of this interface (determined by using the GetProcAddress
API). Each plug-in is packaged in its own DLL (or multiple DLLs) that must be
deployed at the location the application expects them in ordered to be detected
and loaded by the application.
Low-level design
As C++ does not offer a language construct to model the
concept of an interface, we will use the next best thing available: an abstract
base class.
Also, because the Win32 API GetProcAddress uses a
function name as a parameter, while our plug-ins are C++ (because they need to
provide a concrete derivative of the abstract base class) and because C++ does
function name mangling, our plug-ins will need to export as a minimum one C-style
function to act as the class factory. To keep things balanced and because
the application has (in theory) no way of knowing what allocation strategy each
plug-in factory function uses, it only makes sense to ask plug-ins to also
export the counter-part of the factory function, another C-style function to
act as the plug-in clean-up / tear-down procedure.
So, to sum it up:
·
The main program has an abstract class through which it will use
all dynamically loaded plug-ins. It also has a few lines of code to scan a
known location and look for DLLs that export two known C-style functions: the
plug-in factory and the plug-in clean-up.
·
Each plug-in has a class implementing the abstract class in the
main program, and is packaged as a Win32 DLL exporting two C-style functions:
the plug-in factory and the plug-in clean-up.
This is illustrated in the diagram below. As you can see,
there is no registration required, no need for the user to have special
privileges on the machine, no framework / runtime dependency other than what
you already have: C++ and Win32.
The code
Below is a sample “contract” (abstract class) in the main
program that plug-ins will need to implement. Of course, the methods of this
class are going to be specific to what your plug-ins need to do:
//////////////////////////////////////////////////////////////////////////
// Abstract base class
("interface") for the concrete plugin implementations
class IPlugin
{
public:
//Add whatever
functions each plugin needs to implement
//Those below are
just dummy examples to illustrate the principle
//returns the name
of the concrete plugin
virtual const char* Get_Name
() const = 0;
//does the actual
data processing
virtual void Process_Data () = 0;
};
/////////////////////////////////////////////////////////////////////////
//Extern "C" functions that
each plugin must implement in order to be
//recognized as a plugin by us.
// Plugin factory function
//extern "C" IPlugin* Create_Plugin
();
// Plugin cleanup function
//extern "C" void
Release_Plugin (IPlugin* p_plugin);
Below is the code in the main program that scans for
plug-ins, determines that they are indeed exporting the two C-style functions
it expects from a plug-in, then loads and executes each plug-in found:
#include "IPlugin.h" //for the IPlugin abstract base
//convenience typedef for the pointers
to the 2 functions we
//expect to find in the plugins
typedef IPlugin* (*PLUGIN_FACTORY)();
typedef void
(*PLUGIN_CLEANUP)(IPlugin*);
int main(int argc, char* argv[])
{
//get the program's
directory
char dir
[MAX_PATH];
::GetModuleFileName (NULL, dir, MAX_PATH);
//eliminate the
file name (to get just the directory)
char* p =
::strrchr (dir, '\\');
*(p + 1) = 0;
//find all DLLs in
the plugins subdirectory
char
search_parms [MAX_PATH];
::strcpy_s (search_parms, MAX_PATH, dir);
::strcat_s (search_parms, MAX_PATH, "plugins\\*.dll");
WIN32_FIND_DATA find_data;
HANDLE h_find = ::FindFirstFile
(search_parms, &find_data);
BOOL f_ok = TRUE;
while (h_find
!= INVALID_HANDLE_VALUE && f_ok)
{
//load each
DLL and determine whether it is exporting
//the
functions we care about
char
plugin_full_name [MAX_PATH];
::strcpy_s (plugin_full_name,
MAX_PATH, dir);
::strcat_s (plugin_full_name,
MAX_PATH, "plugins\\");
::strcat_s (plugin_full_name,
MAX_PATH, find_data.cFileName);
HMODULE h_mod = ::LoadLibrary
(plugin_full_name);
if
(h_mod != NULL)
{
PLUGIN_FACTORY
p_factory_function =
(PLUGIN_FACTORY) ::GetProcAddress
(h_mod, "Create_Plugin");
PLUGIN_CLEANUP
p_cleanup_function =
(PLUGIN_CLEANUP)
::GetProcAddress (h_mod, "Release_Plugin");
if
(p_factory_function != NULL &&
p_cleanup_function !=
NULL)
{
//yes,
this DLL exposes the 2 functions we need,
//it is a plugin
we can use!
//invoke
the factory to create the plugin object
IPlugin* p_plugin =
(*p_factory_function) ();
//show
which plugin it is, and let the plugin
//do
the processing
printf ("Now working with plugin: %s\n",
p_plugin ->Get_Name ());
p_plugin
->Process_Data ();
//done,
cleanup the plugin by invoking its
//cleanup
function
(*p_cleanup_function)
(p_plugin);
}
::FreeLibrary (h_mod);
}
//go for the
next DLL
f_ok = ::FindNextFile (h_find,
&find_data);
}
return 0;
}
And finally, here is the code for one such plug-in:
#include "stdio.h"
#include "..//MainProgram//IPlugin.h"
////////////////////////////////////////////////////////////////////////
// A concrete plugin implementation
////////////////////////////////////////////////////////////////////////
// Plugin class
class Plugin1 : public
IPlugin
{
public:
//returns the name
of the concrete plugin
const char* Get_Name () const
{
return
"Plugin1";
}
//does the actual
data processing
virtual void Process_Data ()
{
for (int i = 0; i < 3; i++)
{
printf ("Plugin 1 is processing....\n");
}
printf ("Plugin
1 processing done!\n");
}
};
extern "C"
{
// Plugin factory
function
__declspec(dllexport) IPlugin* Create_Plugin ()
{
//allocate a
new object and return it
return
new Plugin1 ();
}
// Plugin cleanup
function
__declspec(dllexport) void
Release_Plugin (IPlugin* p_plugin)
{
//we
allocated in the factory with new, delete the passed object
delete
p_plugin;
}
}
But wait: what about the promise that the user won’t even
have to re-start the application after deploying a new plug-in? For that, just
throw in a couple more Win32 APIs: as the application starts, create a
low-priority thread that calls FindFirstChangeNotification / FindNextChangeNotification
/ WaitForSingleObject or WaitForMultipleObjects and this thread
can notify every time a valid plug-in DLL is deployed at the known location –
so that the application can act (start using the plug-in / ask user whether to
enable the plug-in, etc.).
Other enhancements
- As mentioned above, in most cases if you want the
application to dynamically sense when plug-ins are deployed and run them
without having to re-start, you will need a disk monitoring thread like
the one described above.
- You will probably want to implement versioning on your
program’s contract with the plug-ins. After all, it’s very likely that
your plug-ins interface will evolve over time, and you want the program to
be able to ignore / reject plug-ins that were not written for its version
of the contract (e.g. user deploys plug-ins written for a more recent
version of the program on an older version of the program and vice versa).
Such a versioning protocol can be implemented in the abstract class that
represents your program’s contract with the plug-ins, so that the program
can decline using plug-ins that don’t conform to its versioning
requirements.
- Sometimes the plug-ins may need to add to the
application’s help (CHM) files. I will not get into the details, but it
can be done quite easily if the main program’s help file is properly written
for file merging. If the plug-in is deployed together with its help file,
the Windows help engine can automatically merge the main program’s CHM help
file with each of the plug-ins CHM help files, resulting in a seamless
user experience. Maybe I will address this in another article – until
then, Google “Merging Help Files at Run Time”. I have done this and I know
it works fine without any pain.
I have implemented this pattern since 1998 with great
results. One of the free programs available from this site (daVinci) uses this
architecture to implement parsers for different file formats. As a user needs a
parses for another file format, we implement it and make the parser available
for download on our site. The user downloads the parser and deploys it under
the “parsers” subdirectory of the application (without even closing the
application), and all of a sudden the application can handle the new file format.