CPJNPOP3Connection v1.45 an MFC class to encapsulate the POP3 protocol

Welcome to CPJNPOP3Connection, a freeware MFC class to support the POP3 (Post Office Protocol v3) protocol. POP3 for those not familiar with all the internet protocols is the protocol used to retrieve internet email.

Please note that as of v1.42, the code is now for Visual C++ 2005 or later. I will not be supporting VC 6 anymore for this code, so please don't email me requesting this<gg>. Remember VC 6 is now a ten year old compiler. It's now time to upgrade to VC 2005 or VC 2008!

References

• For information about POP3 (Post Office Protocol v3) you should read RFC 1939.
• RFC 822 and RFC 2822 define the ways standard headers are used by SMTP/POP3.
• RFC 2110 and RFC 2557 which covers MHTML (aka HTML Email).
• Base64 encoding which is used in various places in SMTP/POP3 is described in RFC 1113 and RFC 1421. If was eventually referred to as Base64 in RFC 2045

Features

• Simple and clean C++ interface.
• The interface provided is synchronous which provides an easier programming model than using asynchronous sockets.
• The code does not rely on the MFC socket classes. These classes have a number of shortcomings, one of which causes problems when they are used in NT services.
• The code can be used in a console application without any problems (Again this is not the case for the MFC socket classes).
• A configurable timeout for the connection can be set through the class API.
• Supports APOP as well as clear text authentication.

The enclosed zip file contains the CPJNPOP3Connection source code and a simple test program to exercise all of the functions the classes provide.

Copyright

• 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.

Updates

V1.1 (28 June 1998)

• Fixed a potential buffer overflow problem in Delete and Retrieve functions when a large message number was specified.
• Improve the ReadResponse code by:
  i) passing the readability check onto the socket class and
  ii) Sleeping for 100 ms prior to looping around waiting for new response data
• Classes are now fully Unicode compliant. Unicode build configurations are also now included.
• Now supports the TOP POP3 command which can be issued using the GetHeader function.
• Fixed a few typos in the documentation.
• Thanks to Chris Davidson for the all the suggestions and bug fixes.

V1.11 (4 January 1999)

• Minor update to the documentation.
• Now includes VC 5 workspace files as standard.
• Properly Unicode enabled all the code as previously the code exposes an Ascii(LPSTR/LPCSTR) API instead of a TCHAR / CString API.

V1.12 (22 February 1999)

• Default timeout for the code when a debug build is built has now been set to 60 seconds.
• Improved the reading of responses back from the server by implementing a growable receive buffer.
• Updated instructions on how the relevant RFC documents can be retrieved.

V1.13 (25 March 1999)

• Fixed a memory leak in the CPJNPOP3Connection::ReadReturnResponse function.
• Now sleeps for 250 ms instead of yielding the time slice. This helps reduce CPU usage when waiting for data to arrive in the socket

 V1.14 (15 June 1999)

• Added functions to return the message body, header or a particular header field of a message.
• Tidied up some of the TRACE messages which the code generates.
• Fixed some typos and spelling mistakes in the help file.

V1.15 (16 June 1999)

• Fixed a bug in the GetHeaderItem function which was causing a header item which appeared at the beginning of the header fields to fail to be parsed incorrectly.

V1.16 (27 June 1999)

• Fixed a bug in the GetHeaderItem function when a header spanned multiple lines as is allowed by RFC 822.

V1.17 (29 June 1999)

• Another improvement to GetHeaderItem. When will it end <g>. Originally this was reported as a bug but upon further investigation it turns out that the message which was causing the problems had embedded tabs in the header. This is discouraged by the RFC which refers to mail headers (RFC 822). The code has been enhanced to handle this case. Thanks to Chris Bishop for spotting this.
• Fix for a bug in GetHeaderItem where I accidentally was using "=" instead of "==". Thanks to Angelini Fabio for spotting this.
• Updated documentation to refer to RFC 822.

V1.18 (5 July 1999)

• Addition of the following functions:
  i) CPop3Message::GetReplyTo()
  ii) CPop3Message::GetRawBody 
  iii) CPop3Message::GetSubject 
  iv) CPop3Message::GetFrom 
  v) CPop3Message::GetDate 
• GetHeaderItem function now uses case insensitive searching.
• GetHeaderItem now allows you to search for the "n'th" header of a specified type.

V1.19 (24 August 1999)

• Fixed a bug whereby the function GetHeader was sometimes failing when it was called when the message was retrieved using the "TOP" command.

V1.20 (26 March 2000)

• Fixed a problem where GetBody and GetRawBody will fail if you call it for a CPop3Message object that doesn't have a message in it (i.e m_pszMessage == NULL). This was previously causing a goof old access violation in GetRawBody.

V1.21 (20 September 2000)

• Fixed a bug in CPJNPOP3Connection::UIDL when message id's were returned with embedded dots in them. Thanks to Konstantin Vasserman for finding and resolving this problem.

24 March 2001

• Updated the documentation and copyright info.

V1.22 (27 July 2001)

• Added two methods namely: GetTo() and GetCC() to the CPop3Message class.

V1.23 (11 August 2001)

• Fixed a bug in CPJNPOP3Connection::ReadResponse where determining the terminator was failing when an embedded NULL was in the message.

V1.24 (27 September 2001)

• Fixed a bug in CPJNPOP3Connection::ReadResponse when handling disconnection errors. Thanks to Yuheng Zhao for spotting this problem.
• Improved the error handling in Delete, GetMessageSize & GetMessageID methods. Thanks to Maxim Y. Melnik for spotting this problem.

V1.25 (29 September 2001)

• Further improved the error handling in CPJNPOP3Connection::ReadResponse

29 March 2003

• Initially I was intending adding file attachment support to the class and numerous people have requested this feature but during my research I came across a much more fully featured C++ encapsulation of MIME that I could possibly implement. The project itself is called Mime++ and the URL is http://www.hunnysoft.com/mimepp/. The classes provided are nicely implemented in C++ and integrate well with both MFC and my CPJNPOP3Connection classes. This software is commercial. Alternatively you could use CDO for Windows 2000 to parse what is returned by the class. I do not propose to add support for attachments in the future so please no more emails asking for this!!

v1.26 (5 July 2003)

• Added copy constructors and operator= methods to the CPop3Message class. Thanks to "Sten" for pointing out this omission.
• Made destructors of all classes virtual.

v1.27 (21 July 2003)

• Class now preserves last command response across calls to Disconnect. This is especially important in calls to Connect when for example you get the POP3 error "-Err. Can't lock the mailbox" or something like this when you call Connect. Thanks to "Lev Elbert" for reporting this problem and providing the fix.

18 August 2003

• Christian Andersen has taken the CPJNPOP3Connection class and developed a version runs on Windows CE. The code can be downloaded here. I would ask you to forward any queries relating to this code to Christian as I am only hosting the code as a favor to him.

v1.28 (3 November 2003)

• Simplified the code in CPJNPOP3Connection::ReadResponse. Thanks to Clarke Brunt for reporting this issue.
• Reviewed the various trace statements in the code.

v1.29 (6 November 2003)

• Fixed a problem with an unitialized "m_pszMessage" in the CPop3Message constructor. Thanks to Michael Gunlock for reporting this problem.

v1.30 (12 November 2003)

• Fixed a bug in the CPop3Message operator= method. Thanks to Henrik Grek for reporting this bug.

v1.31 (5 June 2004)

• Fixed a bug in CPJNPOP3Connection::ReadResponse, where the wrong parameters were being null terminated. Thanks to "caowen" for this update.

v1.32 (4 July 2004)

• Added an IsConnected() method to the CPJNPOP3Connection class. Thanks to Alessandro Rosa for this addition.
• Added two new helper functions, namely CPop3Message::GetEmailAddress and CPop3Message::GetEmailFriendlyName. Thanks to Alessandro Rosa for this suggestion.

v1.33 (9 August 2004)

• Fixed a number of compiler warnings when the code is compiled with VC.Net 2003

v1.34 (28 March 2005)

• Fixed a number of compiler warnings in the sample app when the code is compiled with VC .NET 2003.
• Timeout now defaults to 5 seconds in debug mode.
• Added support for connecting via Socks4, Socks5 and HTTP proxies
• Added support for POP3 via SSL. Thanks to Serhiy Pavlov and Alexey Kuznetsov for suggesting this update. Please note that because I do not have access to a mail server which provides POP3 over SSL, you should consider this support preliminary until I get feedback from users of this feature. The standard POP3 support is still fully functional and tested of course.

v1.35 (9 April 2005)

• Updated the initialization code for OpenSSL in the sample app to avoid memory leaks. Thanks to Alexey Kuznetsov for reporting these issues. You should implement the same initialization and cleanup code in your applications. For details please check the code in "main.cpp" module which is enclosed in #ifndef POP3_NOSSL_SUPPORT / #endif sections.
• "List" function is now public instead of protected. Thanks to Alexey Kuznetsov for reporting these issues. 
• Addition of a simple "FindMessageID" which returns the Message index given a message ID as returned via UIDL. Thanks to Alexey Kuznetsov for this addition.

v1.36 (8 February 2006)

• Updated the documentation to use the same style as the web site.
• Removed the unnecessary resource.h from the download zip file.
• Fixed a /Wp64 compile issue in CPJNPOP3Connection::FindMessageID. Thanks to Alexey Kuznetsov for reporting this issue.
• Updated copyright details.
• Renamed the classes to include a PJN prefix inline with my SMTP class.
• Provided a PJNPOP3_EXT_CLASS to allow the class to be easily added to an extension dll
• Did a spell check of this document.
• Changed the pre-processor macro to exclude SSL support to be CPJNPOP3_NOSSL. This is to maintain consistency with my SMTP class.
• Changed the default release mode timeout to 60 seconds and the default debug mode timeout to 90 seconds. This is to maintain consistency with my SMTP class.

v1.37 (13 February 2006)

• Fixed a graceful disconnect issue in CPJNPOP3Connection::ReadResponse.

v1.38 (9 July 2006)

• Optimized CPJNPOP3Message constructor code.
• Code now uses new C++ style casts rather than old style C casts where necessary.
• Optimized CPJNPOP3Connection constructor code
• All classes now uses exceptions to indicate errors. This means the whole area of handling errors in the code is a whole lot simpler. You should carefully review your code as a lot of the return values from methods (especially CPJNPOP3Connection) are now void and will throw CPJNPOP3Exception's.
• General rework of the class to bring it in line with the author's CPJNSMTPConnection code
• Update the code in the sample app to TRACE out what it is doing
• Updated the code to clean compile on VC 2005

v1.39 (20 November 2006)

• Minor update to the sample app to allow it to clean compile on VC 2005
• Optimized ReadResponse method so that if an error occurs while reading the "RETR" response, only the actual command text is set into m_sLastCommandResponse instead of the whole message. This avoids a great performance hit on Unicode projects because of the m_sLastCommandResponse CString nature (ANSI -> UNICODE conversion). Thanks to Alexey Kuznetsov for reporting this issue.

v1.40 (21 July 2007)

• Updated copyright details
• CPJNPOP3Connection::Connect, Delete, Statistics, List, UIDL, Reset, Noop and GetMessageHeader methods now catch CWSocketException exceptions and rethrow them as CPJNPOP3Exception exceptions. This allows client code to only expect CPJNPOP3Exception exceptions to be thrown from the class. Thanks to Alexey Kuznetsov for reporting this issue.

v1.41 (31 December 2007)

• Updated sample app to clean compile on VC 2008
• CPJNPOP3Exception::GetErrorMessage now uses the FORMAT_MESSAGE_IGNORE_INSERTS flag. For more information please see Raymond Chen's blog at http://blogs.msdn.com/oldnewthing/archive/2007/11/28/6564257.aspx. Thanks to Alexey Kuznetsov for reporting this issue.
• CPJNPOP3Exception::GetErrorMessage now uses Checked::tcsncpy_s if compiled using VC 2005 or later.
• Sample app shipped with download is now a VC 2005 solution

v1.42 (18 March 2008)

• Updated copyright details
• The code now only supports VC 2005 or later.
• Simplified the response parsing considerably through the usage of CStringA
• Fixed logic which terminates the parsing loop in ReadListResponse
• Improved the robustness of the ReadUIDLResponse parsing logic
• Now includes support for APOP authentication. Thanks to "goodsiwen" for prompting this update.

v1.43 (18 May 2008)

• GetHeaderItem now uses a CStringA parameter instead of CString. Thanks to Alexey Kuznetsov for reporting this issue.

v1.44 (31 May 2008)

• Code now compiles cleanly using Code Analysis (/analyze)

v1.45 (14 June 2008)

• Updated code to compile correctly using _ATL_CSTRING_EXPLICIT_CONSTRUCTORS define