LHMail is a library created as part of the LeftHand project, but implemented as a standalone component, allowing it to be used in many applications that require e-mail functionality. LHMail was created by Pawe³ Marciniak in C++ using Qt, so it can be used on all platforms supported by Qt: Linux, Windows and others.

The most important feature of the library is its ease of use - sending and receiving an e-mail is literally a matter of a few lines of code. Mail functionality uses Qt's network subsystem, which is asynchronous, so it may happen that a method called to execute a specific task returns immediately, and the task is then executed asynchronously in another application thread. In Qt, the completion of such tasks is indicated by emitting a signal, and LHMail follows the same convention, with the LHSmtp and LHPop3 classes providing signals to notify of incoming messages, sent messages or a completed server connection.

Why another e-mail library?

As already mentioned, the library was created as part of the LeftHand project, or more specifically for the purposes of the LeftHand CRM application. The CRM project required a library that could rapidly be integrated into the existing application framework for the LeftHand CRM (and LeftHand accounting software) to add e-mail client functionality. The idea was to develop an e-mail client that would be similar to popular applications such as Outlook or Evolution, but would be able to access the relational database used by LeftHand applications as well as the existing mailing subsystem. Of course, several libraries offering similar functionality already exist - libEtPan! and DataReel are two examples. However, LeftHand CRM is a closed-source project, so GPL-licensed libraries such as LibEtPan! could not be used. Also, we didn't want to make the project dependent on complex, all-singing libraries that offer functionality far in excess of what was required (DataReel comes with support for Telnet, HTTP, POP3 and SMTP, as well as database support, which is already built into Qt itself). An additional consideration for the LeftHand project was that all libraries are delivered in the installation package, which should be kept reasonably compact. It therefore seemed sensible to create a custom library to serve one specific purpose: provide the required e-mail support. Its code was released into the public domain in the hope that it will be useful for other applications (including commercial, closed-source projects) and might in the future be taken up by programmers other than the LeftHand team.

Figure 1. POP3 client application with a few messages

LHMail capabilities

Key features offered by the LHMail library include:

• support for SMTP and POP3,

• defining and calling external applications based on file extension associations,

• a widget for browsing messages both as plain text and HTML (with images and links),

• saving and reading incoming and newly created messages,

• parsing and validation for multiple e-mail addresses,

• message attachments (both files and other messages for forwarding).

API overview

The key element of the library is the LHMail class, representing a single e-mail. Users create LHMail objects and send them to recipients using the LHSmtp object, and the library itself creates new LHMail instances using the LHPop3 object as new messages are received. Creating a new e-mail is a matter of creating a new LHMail object by passing the required information to the constructor (sender address, recipient addresses, subject and content). You can also use the del parameter to specify that the object should be automatically deleted after the message is sent, which is useful for messages that are sent asynchronously (i.e. from a thread other than the main program loop). Listing 1 presents a complete example of using the LHMail constructor. Key methods on the LHMail class are attachFile(), attachMail() and attachHtml(), allowing respectively file attachments, forwarded e-mails and HTML messages to be sent.

Listing 1. The two key methods of the POP3 client

void Receiver::getMails()
{
      pop3 = new LHPop3 (pop3_server->text (), user->text (), pass->text ());
      
      connect (pop3, SIGNAL (status(const QString &)), 
               sendStatus, SLOT (setText(const QString &)));
      connect (pop3, SIGNAL (newMail(LHMail*)), 
               this, SLOT (newMail(LHMail*)));
 
   pop3->getAllMails (dele->isChecked());
}
 
void Receiver::newMail (LHMail* mail)
{
   mail_list.append (mail);
   new LHMailListViewItem (mail, mails, message, files); 
}

Objects of the LHSmtp class correspond to mail accounts on an SMTP server. Each object can send any number of e-mails. Messages are sent asynchronously, so you should be careful when deleting LHSmtp objects, as they could still be sending data. Just three aspects of the LHSmtp class are immediately relevant to the programmer: the constructor, the send() method and the signals sent to indicate object state. The constructor takes a single argument in the form of the name or IP of the host running the SMTP service. The send() method also takes a single parameter: an LHMail object corresponding to a single e-mail. As far as signals go, status and error use a QString value to notify the user of object state changes, disconnected informs that a server connection has been completed, sentMail indicates that a single e-mail was sent and bytesWritten signals the number of bytes written. No support for SMTP authorisation is currently available, but it is planned for future releases of the library.

A d v e r t i s e m e n t