Black Box Email - Main Report
By Duncan Strand

Email me about this report

Table of Contents

Introduction
Decisions
CPOP3 and CSMTP Classes
Look and feel
Document - View
Files vs. Database
File Formats
Development
Classes

CComposeDialog
CPop3Connection
CPop3Message
CPop3Socket
CBase64Coder
CSMTPAddress
CSMTPAttachment
CSMTPConnection
CSMTPMessage
CSMTPSocket
CAboutDlg
CAccountsDlg
CAccountsPropertiesDlg
CEditFilter
CFilterListDialog
CNewFolderDlg
COptionsDlg
COptionsDisplay
COptionsGeneral
CSendReceiveThread
SendAndReceive
SendEmails
CSendReceiveDlg
CSwitchUsersDlg
Account
Accounts
Configuration
Filter
EmailFolder
DeletedEmails
OutBox
EmailMessage
Folders
EmailStorage
User
Users
CFileString
CBlackBoxEmailApp
CBlackBoxEmailDoc
CBlackBoxEmailView
CMainFrame
CFoldersBar
CAddressCtrl
CFoldersCtrl
CMessagesBar
CMessagesCtrl

Testing
Summary and conclusions
Acknowledgements
Appendix A Development history
Appendix B Progress reports
Appendix C Revised time plan
Appendix D System diagram
Appendix E Terms of reference

Introduction

This is the documentation of the Black Box Email program, not how to use it, but how it was developed, what decisions were made and why, and details about the program.

During the development of the program I kept a log of what I had been doing, and what problems were encountered (included in appendix A)

I have chosen not to include a printout of the source code as at 160+ pages I feel this is a little excessive when I have included the source on a disk (virus checked using the latest data files). The disk also includes all the project files for use in Visual C++ 6 Service pack 4.

This program has been shown to run on any PC running Windows98, WindowsNT4 and Windows2000.

A copy of this report will be made available online at: www.zebs.org.uk/ass/cprj3051

Decisions

During the development of Black Box Email I was faced with a number of big decisions. These decisions were to have lasting consequences throughout the development of the program.

CPOP3 and CSMTP Classes

Before deciding on what project to do I knew that to be able to write this program in allotted time that I would need additional prewritten classes to do the actual sending and receiving of emails. After some searching I found the CPOP3 and CSMTP classes. After an examination of the classes I could see that these were ideal, they were also freely distributable allowing me to use them without any restrictions. I discussed this with my supervisor to ensure that using classes written by someone else was allowed and we agreed that it was, particularly as it shows evidence of reuse.

Look and feel

To help provide a nice looking and configurable user interface I opted to use the BCGControlBar library. This is an extension to MFC that helps the programmer create an application that visually behaves like a MS Office 2000 application.

Document View

I considered the option of using the document view architecture available with MFC, and ultimately decided to take advantage of certain aspects of it, and ignore other less suitable parts, I also needed to consider how the BCGControlBar GUI library would work if using a dialog based application.

Files vs. Database

When I first started development it was my intention to store the users emails in a database and use the MFC classes CDaoRecordSet and CDaoDatabase, as this would minimise the amount of work needed to save the emails and would mean that the manipulation (copying, moving and deleting) of the emails would be significantly easier. There were however several issues that needed to be dealt with before hand.

At the initial stages of development I was using the CPop3Message class throughout the program as the EmailMessage class (since it has all the features that were needed at that stage). Using a database required that the data be transferred from the database into a collection of CPop3Message objects which for a large collection of message would have proven to incur a significant overhead not only with processing the database and CPop3Message, but ensuring that the in memory array of CPop3Messages were synchronised with the database.

By not using a database I would be faced with the task of writing the code to store the emails to disk and manipulate them. Which after a lot of thought and deliberation I decided wasn't going to be as much of a challenge as originally thought. All that was needed was for the email message class to keep a record of its position with in the email file and for a count of the number of emails in the file be maintained.

File Formats

There are two different types of files created by Black Box Email, a file that stores the details of all the users, and a set of files that are used to store the users emails.

The user.dat file is used to store the details of each user, their accounts and any configuration options they have selected.

The user data file starts with the string "BlackBoxEmail User Datafile ver1", if the format of this file is changed at a later time changing this string when the data file is saved will mean that the new data file cannot be used in older versions of Black Box Email and that the new version will either display an error when loading an older data file, or know how to load it and convert it into the new format.

The content of the file then follows the following format:

The number of users, for each user

The users Black Box Email username
The users password
The name of the default email account
The number of accounts this user has, for each account

The account name
The name of the user
Users organisation
Users email address
Users reply to address
POP3 server name
POP3 username
POP3 password
POP3 server port number
POP3 server timeout
Leave a copy of the messages on the server
Exclude this account when checking email
SMTP server name
SMTP user name
SMTP password
SMTP server port number
SMTP server timeout

The string "FOLDERS" and check that its ok.
The number of folders this user has, for each folder

The name of the folder
The number of subfolders (if any), for each subfolder
The name of the folder

The configuration options (currently unsaved)

The files storing the users emails use a very simple format. The first 4 bytes of the file contain the total number of emails in the file (the email count). This number is updated when a new email is written to the file.

Each email message stores the following information

• MessageID
• From
• Subject
• ReplyTo
• Body
• Header
• Priority
• To
• Cc
• Bcc
• Date
• Deleted

All the data is saved as string, the length of the string is stored just before the string itself.

Development

Figure 1

To help get a proper understanding of using Visual C and of any potential issues involved I decided to create a small test application that was capable of downloading viewing and storing emails from multiple accounts, this is shown in Figure 1

The main issue, the one that was to remain undecided for a long time, was first encountered with this program. How to store the emails? In the screen grab the program is using a database to store the users email.

Once the test program was finished I began developing the main application. I experimented with Visual C++ AppWizard and the different settings for the BCGControlBar library, in the process gaining a greater understanding of both Visual C, and the BCGControlBar library. Even before experimenting I had decided that the first important feature to be implemented would be having the list of messages and a list of folders displayed. Fortunately the BCGControlBar took the first step of actually creating them out of my hands as it can do it automatically.

Originally I had hoped to avoid the use of pointers in this project, having, in a previous project spent more time than was necessary debugging one very small error, it would have also avoided any problems with null pointers and memory leaks. However copying one instance of a class to another caused problems that could only be easily fixed by using pointers.

Development then started to continue at a reasonably steady pace, the only serious problem being the list of emails not displaying the list.

Eventually I added the CSMTP classes to the program and created the first version on the compose window. The first email sent from the program using the user interface (as opposed to hard coded) was:

Return-Path: <>
Received: from zaphod ([62.255.233.229]) by mta05-svc.ntlworld.com
(InterMail vM.4.01.02.27 201-229-119-110) with SMTP
id <20001114195830.REZI5562.mta05-svc.ntlworld.com@zaphod>
for <dstrand@ntlworld.com>; Tue, 14 Nov 2000 19:58:30 +0000
From:
To: dstrand@ntlworld.com
Subject:
Date: Tue, 14 Nov 2000 19:58:09 +0000
X-Mailer: BlackBox Email v1
MIME-Version: 1.0
Content-type: text/plain; charset=US-ASCII
Message-Id: 20001114195830.REZI5562.mta05-svc.ntlworld.com@zaphod

Obviously as the 'From:" and "Subject:" fields are blank there was a small problem with the code inserting these values.

Originally the compose window was based on the CFrameWnd MFC class and used the Document -View architecture, however I decided that this was unnecessary for what is really a simple window, and replaced it with a dialog.

One very serious problem encountered at this stage was how to deal with the CSMTP class. At the time the EmailMessage class was a subtype of CPOP3Message and there were no methods with which to update the contents of the email – as would be needed when creating emails. After some deliberation I decided to remove CPOP3Message as the super class of EmailMessage. This change took approximately one evening.

As the deadline drew closer it became clearer and clearer that the program wasn't going to be finished on time, and whilst most of the main features are there a few aren’t. Currently email filtering has not been implemented, replying to an email is possible but the message being replied to is not indented with the '> ' marker. When an email is sent, it is saved in the outbox but not yet moved after being sent to the sent emails folder. This report is based on the program as it currently is, development will be continuing up until the demonstration. At the suggestion of my supervisor I created a revised – and more detailed – two week time plan (included in appendix b) which with the exception of email filtering was kept to.

Classes

For each class I will describe its purpose, and briefly describe the attributes in the class.

Figure 2

CComposeDialog

This dialog is used to allow the user to create a new email, or reply to an email.

When the dialog is created, unlike most dialogs this does not block the user from the rest of the application.

All the 'To', 'Cc', 'Bcc', and 'Subject' fields are CEdit controls. The message area – where the user edits their email is a CRichEdit control.

When the user clicks on the send button a new instance of the EmailMessage class is created and stored in the Outbox, and unless the user choose to send the email at a later date a new thread is created using the SendEmails function.

Currently there is not option to save the message and continue editing it at a later date.

Attributes

CPop3Connection

This class is Copyright (c) 1998 - 2000 by PJ Naughter. This class manages and controls the connection to a POP3 server.

CPop3Message

This class is Copyright (c) 1998 - 2000 by PJ Naughter. It contains all the data relevant to the email message and various different methods to retrieve the data from the email.

CPop3Socket

This class is Copyright (c) 1998 - 2000 by PJ Naughter.

This class is only used by the CPop3Connection class and is not directly used by the application.

CBase64Coder

This class is Copyright (c) 1998 - 2000 by PJ Naughter. This class is used for the encoding and decoding of email attachments.

CSMTPAddress

This class is Copyright (c) 1998 - 2000 by PJ Naughter. This allows the programmer to set the "To" and "From" addresses in the email that is about to be sent. This is particularly useful for including the users name in the email address.

CSMTPAttachment

This class is Copyright (c) 1998 - 2000 by PJ Naughter. This is an encapsulation a file attachment in the email the user is sending.

CSMTPConnection

This class is Copyright (c) 1998 - 2000 by PJ Naughter. This handles the connection between the users computer and the SMTP server.

CSMTPMessage

This class is Copyright (c) 1998 - 2000 by PJ Naughter. This class is used when sending a message. It contains functions to help build the message. Before an email can be sent the program must convert the EmailMessage into a CSMTPMessage.

CSMTPSocket

This class is Copyright (c) 1998 - 2000 by PJ Naughter. It is a simple wrapper for the Windows network functions.

CAboutDlg

Figure 3

Displays a small dialog briefly detailing some of the legal information about the program and other miscellaneous details.

The web address can be clicked on. This causes the users default web browser to open this projects website.

Of course, there are not any hidden features in this dialog. None at all…

 Attributes

CAccountsDlg

Figure 4

When opened this dialog displays a list of the email accounts available to the user. From here they can add more accounts, change the details of an existing account and remove an account.

By using the "Move Up" and "Move Down" the user can change the order in which the accounts are checked for emails.

The user can change the default account by selecting the account and clicking on the "Set Default" button.

This class only has one attribute, m_Accounts it is a CListBox and is used to display the list of accounts.

CAccountsPropertiesDlg

This class is used to manage the dialog that is used to display the details of an existing email account and add new accounts.

This dialog has three separate pages, one for the accounts general details such as the users real name, one for the SMTP details and finally one for the POP3 details.

Attributes

CEditFilter

Figure 5

This dialog is used to edit an existing email filter and create new ones.

Using this dialog the user can enter the (unique) name of the filter. The conditions of the filter are edited here.

When the user clicks on the Ok button, if a new filter is being created a new instance of the Filter class and filling its attributes as appropriate. If the user is editing an existing filter then the details of the existing filter are changed.

Attributes

CFilterListDialog

Figure 6

This dialog displays a list of the filters that the user has created, and allows the user to add more, delete or modify existing ones and change the order that the filters are checked.

The list of filters is displayed to the user using a CListCtrl, and is internally represented using a CArray.

The content of the list is re-created each time the dialog is displayed.

Clicking on either the 'New…' or 'Edit…' buttons causes the CEditFilter dialog to be opened. The only difference between the two actions being that using the 'Edit…' button causes the dialog to display a filter, whereas the 'New…' button creates one.

CNewFolderDlg

Figure 7

This controls the dialog that is displayed when the user wants to create a new folder.

The user can create a folder as a subfolder of another by entering the name of the new folder and selecting the parent folder in the tree control.

The tree control is passed to the folders class so that the tree of folders can be created. Each node in the tree has a pointer to the EmailFolder class that the node represents.

Attributes

COptionsDlg

This class doesn't have its own display, as it is a Property sheet dialog. The COptionsDisplay, and the COptionsGeneral classes manage the display. This class effectively holds them together.

COptionsDisplay

Figure 8

Figure 9

This class is a property page used by the COptionsDlg class. The controls on this page are used to effect how certain parts of the program operate. Including how long the program should wait before automatically checking if any of the users accounts have any email waiting, whether a sound should be played when new email arrives, and should Black Box Email check for new email when the program is loaded. None of these options have any effect at the moment.

CSendReceiveThread

The CSendReceiveThread creates the Send and receive dialog and ensures that the send and receive dialog does not lock the main application window. This class has one attribute m_SendReceiveDlg, for details about this attribute see CSendReceiveDlg.

SendAndReceive

This isn't a class, but a globally available function. It controls the sending and receiving of email, and all other functions related to dealing with the email servers.

SendEmails

This is not a class, but a globally available function. It sends all the emails in the current users outbox folder.

CSendReceiveDlg

This dialog class is used to display the progress of the emails that are being downloaded, and the emails being sent.

Ticking, or un-ticking, the 'Close when finished' tick box causes the system registry to be updated (all registry keys for this application are stored at: "HKEY_CURRENT_USER\Software\BlackBox Email"). If the box is ticked then the dialog will automatically close when the process of sending and receiving the email is complete.

Attributes

CSwitchUsersDlg

Figure 10

This dialog is used to change the current user. Doing this causes the current settings to be replaced by the new users settings, the users emails to be loaded.

When changing users the user is prompted for the password for the new user (if appropriate).

This class has one attribute called m_Users, it is a CListBox and displays the available users.

When the current user is changed the program saves the current users details, changes the currentUser pointer in the Users class and loads the new users details from the users.dat file.

Account

This class is used to store all the details specific to a single email account and any per account settings. It includes the code to load and save the account to the users.dat file.

Attributes

Accounts

This is a collection of all the users email accounts.

Attributes

Configuration

This class stores all the data specific to the users configuration of the program. It contains an array of all the users email filters, the selected font for displaying emails.

Filter

The filter class is used to store the details of an email filter, and methods to check if a message matches the filter or not.

Attributes

EmailFolder

This is a folder with which the user can store emails in. It contains a collection of references to itself enabling the user to create subfolders. It also includes an instance of the EmailStorage class, when the folder is loaded the LoadEmails method in that class is called.

This class includes code to save the details of the folder to the users.dat file.

Attributes

DeletedEmails

This is a special case of EmailFolder, and as the name suggests is a folder for deleted emails. This class doesn't currently have any unique behaviours, but once the ability to empty the DeletedEmails folder is added it will have a function that actually deletes emails instead of flagging them as deleted.

OutBox

This is a special case of EmailFolder, and as the name suggests is a folder for all emails that are being sent. Although this class doesn't yet have any special responsibilities it will when the ability to delay the sending of emails.

EmailMessage

The EmailMessage class encapsulates an individual email message. It contains methods for obtaining and setting various attributes.

It was methods for reading and writing the message to disk. Methods that wrap the text of the message to a specified width and a method that inserts the email quote characters "> " at the beginning of each line without effecting the original text.

Instances of this class are either created when a user starts a new email message, replies to an existing message, loads the program, or downloads a message. When a message is downloaded the CPop3Message class is passed to a constructor and the data copied.

Attributes

Folders

This is a collection of all the EmailFolders. It includes methods to return the special case email folders, and methods to load and save all the email folders. It is also the class used when moving, copying and deleting emails.

Attributes

EmailStorage

The purpose of this class is to hide all the implementation of how the emails are stored on disk. It is a subclass of the MFC class CArray.

Whenever an operation is performed manipulating an email, be it adding or removing, this class has to be called, as it is the array of emails for the given folder.

Attributes

User

This contains all the details relating to a specific user. Their username and password, their email accounts, configuration settings and a instance of the Folders class.

Calling either the SaveUser, or LoadUser causes the equivalent Load and Save methods in the Accounts, Configuration, and Folders classes.

Attributes

Users

This class contains a collection of all the users of the program and offers methods to access the collection of users.

Calling either the LoadUser or SaveUser causes the Load and Save methods in almost all of the "User" classes.

Attributes

CFileString

This subclasses the MFC class, I use this to simplify saving and loading strings of an unknown length, useful in an email application.

CBlackBoxEmailApp

This class is used to initialise the program when its starting. It creates the user interface, creates (and stores) the instance of the Users class, and stores pointers all the threads that might be running during the lifetime of the program.

Attributes

CBlackBoxEmailDoc

Unused. This is an essential part of the MFC document - View framework that I decided not to make full use of in the project.

CBlackBoxEmailView

This displays the contents of the email to the user. This class is based on the MFC control CRichEditView. Although this custom View doesn't yet have any specific behaviour, this is the class that would be altered to change how the email message is displayed to the user.

For example if the program were to be enhanced so that any web links can be clicked on, causing the users web browser to open, this is the class where that behaviour is implemented.

This class has no attributes except those inherited from the super class.

CMainFrame

This class, based on CBCGFrameWnd, is very much the workhorse of the program. Almost every action by the user is directed through this class. All elements on the main window is defined and controlled by this class.

Attributes

CFoldersBar

This class is the bar that by default appears on the left of the main application window. It inherits from CBCGSizingControlBar – part of the BCG GUI toolkit, which provides all the functionality of the bar.

It contains a CBCGTabWnd control, which has only two tabs. One is a list of email addresses stored in the address book (CAddressCtrl), and the other a list of Folders (CFoldersCtrl).

Access to the tabbed controls is restricted as both controls are private and must be indirectly accessed through this class. This helps ensure that should any changes be made to the two controls only have to reflected here, not everywhere else.

Attributes

CAddressCtrl

This is a custom control based on the MFC control CTreeCtrl. Its purpose is to display a list of email addresses stored in the users address book.

This has no attributes except those inherited from the super class.

CFoldersCtrl

This is a custom control based on the MFC control CTreeCtrl. Its purpose is to display a list of folders, which the user can use to store their emails in.

This only listens to one user input event – OnSelchanged. This is triggered when the user changes the selected folder, causing the list of emails to be changed to show the emails available in the selected folder.

This has no attributes except those inherited from the super class.

CMessagesBar

This class is the bar that by default appears on the top of the main application window. It inherits from CBCGSizingControlBar – part of the BCG GUI toolkit, which provides all the functionality of the bar.

It contains a CBCGTabWnd control, which has only two tabs. One is a list of emails in the currently displayed folders; the other displays the results of the last search. Both are CMessagesCtrl's

Attributes

CMessagesCtrl

This is a custom control based on the MFC control CTreeCtrl. It displays a list of messages in the currently selected email folder. When the user clicks on a message in the control a message is sent to the main window telling it to display the selected message.

This has no attributes except those inherited from the super class.

Testing

All tests were performed after the program had been properly configured.

Program load
This test is to ensure that the program actually loads in is distributable state.

Downloads emails
If the program isn't downloading emails then there is a serious problem.

Excludes selected accounts
This tests that the program is not checking for emails on accounts that the user has said should be ignored.

Deletes emails from server for account configured to do so
Checks that the program is only deleting emails from the server when configured to do so.

Sends emails
Checks that a properly formatted email (i.e. correct address has a subject line and message body) is sent and is received by the destination user.

Badly formatted addresses when sending
Tests what will happen if the email address is badly formatted. For example "bob@home.com side@work.com" should both fail.

No send address
Only a Cc address is specified
Only a Bcc address is specified
Tests what happens when the user has clicked on the send email button (after writing an email) but hasn't entered any email addresses.

No message body
Tests what happens if there is a correct email address and subject but no message body.

No subject
Tests what happens if there is a correct email address and message body but no subject.

No subject, message, or addresses
Tests what happens if the user clicks on the send button without entering with a subject, email address or message body.

Summary and Conclusions

Overall I feel that the development of Black Box Email could have progressed faster, as we were warned at the beginning of the project it is very easy to put of working on the project because the deadline at the time seemed so far away.

If I were to start the writing the program again the only significant changes to my approach would be to fully investigate the MFC document view architecture so that I can totally convince myself that it isn't appropriate (unless it transpires that it is…), and use a dialog based application.

Acknowledgements

PJ Naughter. Both the CPOP3… and CSMTP classes are a major part of this program. Without these classes developing this program would have been significantly harder. Both collection of classes are both used subject to the following conditions as outlined on his website (www.naughter.com)

• You are allowed to include the source code in any product (commercial, shareware, freeware or otherwise) when your product is released in binary form.
• You are allowed to modify the source code in any way you want except you cannot modify the copyright details at the top of each module.
• If you want to distribute source code with your application, then you are only allowed to distribute versions released by the author. This is to maintain a single distribution point for the source code.

Stas Levin. The BCGControlBar, which is responsible for the look and feel of this program. No distribution guidelines are available other than that "BCGControlBar is Copyright© 1999-2000 Stas Levin"

Appendix A - Development History

The version included in the report was printed on the 28th November 2000. The up to date version of the file can be found here.

Appendix B - Progress Reports

1 April 2000

22 August 2000

6 November 2000

13 November 2000

20 November 2000

Appendix C - Revised time plan

Click on the image to get a better look

Appendix D - System diagram

Appendix E - Terms of Reference

Go here.