wxSMTP

From WxWiki
Jump to: navigation, search

wxSMTP is a wxWidgets contrib that allows sending e-mails. MIME format is supported, allowing to format a mail with all existing fields (TO, CC, BCC), as well as attaching files and formatting mail body with html content. The mails are sent by performing a direct connection to a SMTP server, which avoids the need of having a properly configured mail client on the machine where it is run.

The major difference between wxSMTP project and the wxEmail class of the 'net' contrib of wxWidgets is that this last relies on 3rd party libraries/applications (MAPI under Windows, sendmail under Linux). Thus, when sending a mail with wxEmail under Windows, the mail will be sent by the default mail client configured.

The library was originally written by Frank Buß (web site). To see the complete history of this project see section History

The new version of wxSMTP now also supports POP3 protocol. It is thus now possible to retrive e-mails from a mailbox server supporting this protocol.

Build

wxSMTP is available on wxCode. These links lead to wxCode, which leads to wxEmail - link to wxSMTP is unclear, and probably needs to be updated.

The last version is available here. The structure of the project is in conformance with wxCode components rules and so, makefiles and/or project files exist for all wxWidgets supported OS/Compilers.

It has currently only be tested under Windows and Linux platforms. If you have successfuly built the library for another platform, feel free to complete this section. If you encounter troubles when building the library for your platform, you can contact the maintainer of the project.

All compilation options available for wxWidgets have not been tested. In particular, if you have compiled wxWidgets with unicode or as shared libraries, you may encounter problems. Do not hesitate to contact the maintainer.

Windows/Mingw

  • Patch '<wxSMTP>/build/makefile.gcc' to configure the options to match the ones used to compile your wxWidgets main lib.
  • Open a Windows shell
  • Go to the directory <wxSMTP>/build
  • Execute the following command : mingw32-make -f makefile.gcc

Linux/Gcc

  • Open a linux shell
  • Go to directory <wxSMTP>
  • ./configure
  • make

Usage

A sample is available in the last version distribution (<wxSMTP>/samples/SendMail/SendMail.cpp). This illustrates the basics of the usage of the wxSMTP library. The following code snippet illustrates the main functionalities :

   /* Instanciate the message */
   msg = new wxEmailMessage("My e-mail subject",
                            "The content of my mail",
                            "[email protected]");
   
   /* Add the recipients of the mail */
   msg->AddTo("[email protected]");
   
   /* Instanciate the smtp client */
   smtp = new wxSMTP(NULL);
   smtp->SetHost("smtp.domain.com");
   
   /* Initiate the sending process */
   smtp->Send(msg);

NOTE : the API of the new version of wxSMTP has changed. This code snippet is no more up-to-date. See the provided samples for up-to-date examples.

An important remark : the mail is not sent when the wxSMTP::Send function returns. If it was the case, this method would block the GUI during the whole server communication process. The sending process is thus asynchronous, and relies on the main wxWidgets event loop mechanism to perform the different operations. So, the mail will be effectively sent if (and only if)

  • the wxWidgets event loop is running
  • the program waits until the mail is effectively sent before exiting

wxSMTP sends notification status via wxEvents mechanism. This allows the application to be notified when a mail is effectively sent, or when the sending process fails. The sample provided with the library illustrates how this mechanism can be used.

History

Original version by Frank Buß

Newer modified version 1.11, modified 2004-06-29 by Markku Tavasti

Excerpt from a message Tavasti sent to wx-users -

 Things I have done:
 
 - Made wxSMTP & co separate library (Makefile 'works for me',
   supporting building for linux & windows under linux cross compilation)
 - Added writing To, Cc: etc headers
 - Possibility to add alternative parts (text and html in same E-mail)
 All is distributed under wxWidgets license (I have permission from
 Frank Buß). All fixes and enchantments welcome directly to me. 

Contributed version, not tested by tavasti by G. Paul Ziemba <paul at w6yx.stanford.edu>.

Contains error handling.

Version 1.13 by Brice André.

Above link seems to be broken - needs to be updated. This version is ready for an integration in wxCode project. All standard wxWidgets makefiles/project files have been added. The library compiles and runs on wxWidgets 2.8.10. A sample has been added to the project to illustrate the usage of the library.

Roadmap

The new version shall still be consolidated. It shall be tested on different platforms with different configuration options. The API is now considered as mature and should not still be changed in new releases.

Non-English Character encodings is partially supported by the library. Efforts shall still be undertaken to ensure a proper handling of such charsets when sending e-mails.

The name of the component will probably be changed soon as this is now no more only limited to SMTP protocol.

Questions/Answers

QUESTION (from Marc at bowery dot com): How does this differ from wxEmail (contrib/src/net and contrib/include/wx/net) ?

Answer (Helmut Gruber): wxEmail uses MAPI on Windows, and sendmail/postfix on Unix


QUESTION (from Olaf): why is wxSMTP derived from the custom class wxCmdLineProtocol and not from the wxProtocol class?

Answer (Tavasti): That's the way Frank Buß did it. SMTP is CmdLine-type protocol, so there might be good idea on it?

Answer (Frank Buß): My idea was to derive other protocols as well, e.g. FTP, which are command line based, too. I don't know, if this works, maybe delegation and some smaller utility classes are more useful.


QUESTION (from Tom): I tried to get wxSMTP to send an email. I received no errors, or anything else, but I also didn't receive an email. I downloaded and tried to build Wino, to see what I was doing wrong. Shortly afterward I started getting this error every time I tried to build anything:

..\..\include\wx\chkconf.h(76) : fatal error C1189: #error : "wxUSE_CRASHREPORT must be defined."

I tried rebuilding wxWidgets, but got the same error. So, I replaced the setup.h file with the setup0.h file, and still got the same error. After looking to see what files had been modified, I found that my platform.h file had this line commented out:

include "wx/setup.h"

I can't be sure that the fault lies with Wino or wxSMTP, but it's very strange.

Answer (Brice André) : Your problem is probably linked to the remark at the end of the Usage section. In order to ensure that the main event loop is running, the simplest way consists in displaying a wxFrame until the mail is sent. See the sample provided with last version of the lib for more info on how to do so.