Here you have the source code for SpamPal v1.623, which is now open source to foster a sense of trust and community contributions. And so that the project doesn't die if I ever fall under a bus.
This document gives a brief overview of the binary files that SpamPal requires to execute, and also of the source code files which were used to create these binary files.
SpamPal was the first major application I'd ever written in C, and the first time I'd ever used the Win32 API. (I'd previously done some Unix work with C++ and Motif, and but mostly I've been using Java for the last few years.) Therefore, some parts of the source code are maybe not as well-coded as they should be. And while the code is commented to a degree, these comments were intended for my own use rather than public consumption. There is also a lack of the kind of high-level design documentation you would expect to see if this were a professional software project and not something I've written in my spare time. All I can say is that, if you require more detailed information, you can ask in the SpamPal source code forum and I'll get back to you ASAP with an explanation.
Before attempting to modify the SpamPal source code, I suggest that you look at the plugins interface and consider whether what you want to do cannot be implemented as a SpamPal plugin. Plugins are much more portable than modified versions of SpamPal itself, and can be combined in unison to support the user's individual requirements. If you want to add a new type of mail filtering, the likelihood is that this can be accomplished by writing a plugin.
The source code is covered by this licensing agreement. Please read and understand this before doing anything with the SpamPal source code! This license only applies to files in the SpamPal source code archive you have downloaded; it does not apply to any other files on the SpamPal website. If you plan to use SpamPal code in your own product, please invest a moment in checking that you have the rights to use what you want to use.
Please note, and I really cannot emphasize this enough, that SpamPal is not licensed under the GPL.
In order to function, SpamPal requires the following files, all in the same directory:
| spampal.exe | The main executable. Double-click this to run SpamPal. |
| lang.dll | A DLL file containing language-dependant resources. |
| updates.dll | A DLL file containing functions to check for updates to the SpamPal code. These needs to be linked with some Internet Explorer DLLs, so I've put them in a separate DLL so that those DLLs aren't loaded when not necessary. |
| spampalLSP.dll | A Layered Service Provider DLL file to allow the SpamPal transparent proxy to intercept and filter outgoing connections. Compiled from the files in the sub-folder "lsp". |
| default_dnsbl.dat | A text file defining which DNSBL definitions will be used when SpamPal is first run by a user. At an early opportunity SpamPal will download the most recent list of DNSBL definitions from the website and place it in the user's configuration directory; default_dnsbl.dat will only be used when this file is not present. |
| default_extra_dnsbl.dat | The default "extra DNSBL definitions" file. (The "extra DNSBL definitions" are accessed from SpamPal's "Advanced" options pane, and allow the user to use DNSBLs other than those entered by me into the standard DNSBL definitions file, which SpamPal will periodically update.) Again, this file will only be used if there isn't already an "extra DNSBL definitions" file in SpamPal's configuration directory. The format of this file is plain text. |
| extra_dnsbl_instructions.txt | Textfile briefly describing the file format of default_extra_dnsbl.dat; viewed when the user clicks on the relevent help button in the options window. |
| default_filter_processes.txt default_exclude_processes.dat |
These textfiles are default lists of process leafnames which for which the SpamPal transparent proxy should/should not filter email connections. |
In addition, there may be a www directory containing a copy of the manual, which SpamPal will detect and access when the user activates any of the help buttons. (If this is not present, SpamPal will refer the user to equivalent pages on the website.) There may also be other such folders, all starting with "www" for non-English-language helpfiles.
There may also be a plugins directory, which contains any SpamPal plugins that have been installed. SpamPal will automatically scan the plugins folder if it is present, but it is not required for successful SpamPal operation. The plugins directory is described in the plugin API documentation.
Note that an installation of SpamPal may include other files, which have been placed there by the installer to manage uninstalling and upgrading. These are not necessary for the use of SpamPal itself.
Copies of all the essential files can be found in the "installfiles" directory of this archive. You can even run SpamPal from this directory if you want.
SpamPal also requires the ZLib compression library; this is Copyright (C) 1995-2002 Jean-loup Gailly and Mark Adler and is available from http://www.gzip.org/zlib/ - it is supplied with lcc-win32 so I personally didn't have to install it. (The SpamPal executable I compiled requires zlib.dll to be available somewhere on the computer; I've included this in the installfiles directory. This and the supporting files can be obtained from http://www.winimage.com/zLibDll/)
If you can't get zlib to work, then you should note that it's currently only required by the updates-checking; by commenting out the code in spampal.c that calls updates.dll you can get SpamPal to work without it.
SpamPal.exe is compiled from the source files within the code directory of the source code archive. They are written in C using the Win32 API, and compiled using lcc-win32; they should work in other compilers but I haven't tried any. To compile your own spampal.exe, all you should need to do is create a new empty .exe project in lcc-win32, add all the .c and .rc files to it. Then go into the configuration window, and on the "Linker" tab under the heading "Additional files to be included in the link" enter "wsock32.lib shell32.lib". (Users of other compiler systems may need to link with comctl32.lib as well.) You're now ready to use the "Make" option to compile SpamPal.. If you run into any problems, you can ask for help in the SpamPal source code forum.
For users of Microsoft Visual C, there are now SpamPal.dsp and SpamPal.dsw files included in the code folder. These are supplied by James Day and I have not tried them personally.
A description of the files follows:
| spampal.h |
Defines various compilation options, constants and generic global variables. If you uncomment the definition of DEBUG_LOG in here, SpamPal will create a large debugging logfile (probably in C:) when it is run. Uncommenting the various BETA_RELEASE definitions will cause SpamPal to show a warning about it being a beta-release the first time it is run, and it will start to nag the user to upgrade once the specified expiry date has passed. |
| spampal.c |
Contains the WinMain function. This file manages the most basic levels of SpamPal's operation; the Win32 message loop, the tray icon, the tray menu, the "About" dialog, and various miscellaneous setup and shutdown operations. |
| spampal.rc |
Resource script that defines language-inspecific resources, such as the system tray icon. I'm not entirely sure the VERSIONINFO resource definition works, btw. |
| spampalres.h |
Defines the resource identifiers, both for the language-independant resources in spampal.exe and the language-dependant ones in lang.dll. |
| Configuration Management | |
|---|---|
| config.c config.h dnsbl.h |
These files define structures and functions that are used in managing the configuration of SpamPal, and also for managing the currently-loaded plugins. Note that, for some reason which I now can't properly remember, SpamPal supports the idea of multiple configurations in use simultaneously; the global variable currentConfig always points to the most recently loaded configuration. However, a mail session will use the configuration that was pointed to by currentConfig when the session started for the duration of that session. This means that if the user goes into the configuration dialog and changes something whilst a mail fetch is in progress, the modified configuration will not affect that mail fetch. You should use the claimConfig function when you want to make use of a configuration structure, and releaseConfig when you've finished with it. |
| configdialog.c configdialog.h |
These files manage SpamPal's options window, all the associated dialogs, and also the "Add to Whitelist" and "Add to Blacklist" dialogs accessible from the tray menu. Note that when OK is pressed, the configuration is changed by calling saveConfigFromDialog to save the new configuration files, then loadConfig to load them. |
| awlist.c awlist.h |
Defines and manages the "automatic whitelists", including the long lists of "pending" items that haven't quite made it onto the auto-whitelists yet, but may do soon dependant upon future email messages. |
| Mail Fetching & Filtering | |
| pop3.c pop3.h |
Code to manage a POP3 interaction between client and server. Note especially the function fetchPop3Email, which handles the fetching and filtering of an email message. |
| imap4.c imap4.h |
Code to manage an IMAP4 interaction between client and server. |
| smtp.c pop3smtph |
Code to manage a SMTP interaction between client and server. |
| null.c null.h |
Code to handle a 'null' interaction between client & server; data is merely passed, unchanged and unexamined, from one to the other. |
| filtering.c filtering.h |
Contains function that perform the various stages of filtering of an email message, in a manner that is intended to be protocol-unspecific. Also contains functions to both initiate DNSBL queries and make sense of their results. |
| msg.c msg.h msgstatus.h |
Defines structures to represent an email message and its status, and functions for manipulating the email message structure. |
| Networking | |
| notimeout.c notimeout.h |
In order to prevent client time-outs, SpamPal "dribbles" a byte of message header data to the client every few seconds whilst the body is being fetched and filtered. (For some reason, this doesn't work on OE.) These files manage this. |
| listen.c listen.h |
Code to manage the "server sockets" that allow SpamPal to accept incoming connections. |
| dnsblcache.c dnsblcache.h |
Handles the caches of recently-seen positive and negative DNSBL results. |
| multithreadeddnsbl.c multithreadeddnsbl.h |
Code to make DNS queries on a multithreaded basis - ie more than one at once. |
| inetutils.c inetutils.h inetdefns.h |
Various miscellaneous Internet-related functions. |
| Other GUI | |
| statuswindow.c statuswindow.h |
Code to manage SpamPal's status window. |
| updates.h |
Defines structures and function definition types that are used by both spampal.exe and updates.dll. |
| welcome.c welcome.h |
Contains code executed when someone runs SpamPal for the first time, notably the "welcome" window that appears. |
spampal-messagebox.c spampal-messagebox.h |
These files provide a generic message-box feature that is used in many parts of SpamPal. It can handle SpamPal running as an application or GUI client (in which case a messagebox-like dialog is opened automatically), or as a service (in which case a message is sent to the connected GUI clients instructing them to open a messagebox-like dialog). It takes the place of the old mutableMessageBox function that used to be guiutils.c. |
spampal-dialogbox.c spampal-dialogbox.h |
Generic, service-compatible way, of opening blocking dialog boxes. Intended as a substitute for DialogBox() function calls. |
guiutils.c guiutils.h |
Various generic GUI-related utility functions. |
| Transparent Proxy-Related | |
| lsp.c lsp.h |
These files contain various functions dealing with handling of and communication with the Layered Service Provider DLL |
| lsp-comms-buffer.c lsp-comms-buffer.h |
These files define a class which is used to handle communication of protocol-level session data to/from the Layered Service Provider. |
| lsp-install.c lsp-install.h |
Defines functions for installing/removing the Layered Service Provider from the Winsock2 Service Providers database. |
| Service-Related | |
| service-control.c service-control.h |
These files contain a few functions that are used to start & stop the SpamPal service (there's also code concerning this in spampal.c). |
| service-client.c service-client.h |
Definitions and functions that are used to manage communications between a SpamPal windows service, and SpamPal GUI client applications that connect to it to provide user-interface services. |
| MD5 Digest Algorithm | |
|
md5.h md5c.c md5global.h |
The "RSA Data Security, Inc. MD5 Message-Digest Algorithm", taken verbosely from RFC 1321. |
| Graphics files | |
|
bigbrolly.ico smallbrolly.ico greybrolly.ico brollyanim1.ico brollyanim2.ico brollyanim3.ico |
The SpamPal executable icon, the tray icon, and the frames of tray icon animation. |
| hand.cur |
The "pointing hand" used when the mouse pointer is over a hyperlink; for some cunning reason this doesn't seem to be accessible as a standard cursor?!? Nice one Bill. |
|
cbx_checked.ico cbx_unchecked.ico cbx_disabled.ico red_arrow.ico |
Used as status symbols in the trees in the options window |
| Miscellaneous | |
| crash-debug.c crash-debug.h |
A selection of functions that are called by SpamPal to record what each thread is currently doing; these are used to display extended information should SpamPal crash. |
| fileutils.c fileutils.h |
Various utility functions related to the handling of files. |
| lists.c lists.h |
Simple, generic list-handling structures and functions. |
| logging.c logging.h |
Code to manage SpamPal's event-logs. |
| changes.txt |
My own log of changes to SpamPal since about v0.03. |
The directory code/langres/eng contains two source files that can be used to compile an English version of lang.dll, the file containing language-dependant SpamPal resources (including most window definitions). Again, you can use lcc-win32 to compile it; create a new DLL project, add lang.c (which contains nothing of consequence) and spampal.rc (a resource script containing all of the resources), and compile.
You'll need to make sure your compiler links lang.dll with commctl32.lib in order to mak it work."
updates.dll is compiled from the source files within the code/updates directory of the source code archive. They are written in C using the Win32 API, and compiled using lcc-win32; they should work in other compilers but I haven't tried any. To compile your own spampal.exe, all you should need to do is create a new empty .dll project in lcc-win32, add all the .c and .rc files to it. Then go into the configuration window, and on the "Linker" tab under the heading "Additional files to be included in the link" enter "wininet.lib shell32.lib zlib.lib". You're now ready to use the "Make" option to compile updates.dll.. If you run into any problems, you can ask for help in the SpamPal source code forum.
A description of the files follows:
| updates.c |
Code that contacts the SpamPal servers to request a list of updates, and displays results as and when necessary. |
| ../updates.h |
Defines structures and function definition types that are used by both spampal.exe and updates.dll. |
| updates.rc |
Resource definitions for updates.dll. |
| ../spampalres.h |
Defines the resource identifiers, both for the language-independant resources in spampal.exe and the language-dependant ones in lang.dll. |
The spampalLSP.dll layered service provider is compiled from source code in the code\lsp folder. Unlike the other source files, these use C++ and should be compiled with Microsoft Visual C++.
A layered service provider is a very complex thing and rather than offer a full explanation here, I refer the reader to this documents.
SpamPal is a work in progress; I am still working on it myself, and new versions will be forthcoming in the future. Obviously, any changes you make will diverge from the SpamPal distrubution, so it will probably pay you to ensure that changes are as self-contained as possible. Naturally, you will have to make some changes to the source files whatever you do, so it seems prudent if at this point I briefly touch upon my own plans for the short- and medium-term.
Fortunately, these mostly involve the addition of new features rather than the wholesale rewriting of existing ones, and thus changes to the code should be evolutionary rather than revolutionary.
SpamPal is quite a complex application (and probably unnecessarily so); I cannot begin to explain how it works in this document. All I can suggest is that you have a look at the code yourself, and if there's anything you don't understand then post a message on the SpamPal source code forum and I'll answer you at the first chance I get. I would prefer to discuss the source code in the forum rather than email, simply so that other people can benefit from your questions and their answers.