Click here to Skip to main content
Click here to Skip to main content

CPop3Connection v1.19

, 3 Mar 2000
Rate this:
Please Sign up or sign in to vote.
An MFC class to encapsulate the POP3 protocol
  • Download source files - 19 Kb
  • Welcome to CPop3Connection, a freeware MFC class to support the POP3 protocol. POP3 for those not familiar with all the internet protocols is the protocol used to retrieve internet email.

    For detailed information about the Post Office Protocol Version 3 you should read RFC 1725. You should also refer to RFC 822 which contains details on the layout of messages.

    You can find numerous Web Servers which carry these documents by going to www.yahoo.com and look for RFC and 1725 or 822.

    Features
    Usage
    History
    API Reference
    Planned Enhancements
    Contacting the Author

    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.

    Usage

    • To use the class in your code simple include pop3.cpp in your project and #include pop3.h in which ever of your modules needs to make calls to the class.
    • To see the class in action, have a look at the code in InitInstance in the module "main.cpp".
    • Your code will need to include MFC either statically or dynamically.
    • You will need to have a functioning Winsock stack installed and correctly initialized prior to calling any functions in CPop3Connection. Depending on your application, this will involve calling either WSAStartup or AfxSocketInit at startup of your application.
    • You will also need to have afxtempl.h and winsock.h or afxsock.h in your precompiled header. The code will work just aswell in a GUI or console app. The code should also work in a multithreaded application, although it has not be explicitly tested in this scenario.

    History

    V1.0 (18th May 1998)

    • Initial public release.

    V1.1 (28th 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
    •     a) passing the readability check onto the socket class and
    •     b) 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.

    V1.11 (4th 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 (22nd 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 (25th March 1999)

    • Fixed a memory leak in the CPop3Connection::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 (15th 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 this file.

    V1.15 (16th 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 (27th June 1999)

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

    V1.17 (29th 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 (5th 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 (24th 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.

    API Reference

    The API consists of the public member functions of the class CPop3Connection & CPop3Message

    CPop3Connection::Connect
    CPop3Connection::Disconnect
    CPop3Connection::Statistics
    CPop3Connection::Delete
    CPop3Connection::GetMessageSize
    CPop3Connection::GetMessageID
    CPop3Connection::Retrieve
    CPop3Connection::Reset
    CPop3Connection::UIDL
    CPop3Connection::GetMessageHeader
    CPop3Connection::Noop
    CPop3Connection::GetLastCommandResponse
    CPop3Connection::GetTimeout
    CPop3Connection::SetTimeout
    CPop3Message::GetMessageText
    CPop3Message::GetHeader
    CPop3Message::GetHeaderItem
    CPop3Message::GetBody
    CPop3Message::GetReplyTo
    CPop3Message::GetRawBody
    CPop3Message::GetSubject
    CPop3Message::GetFrom
    CPop3Message::GetDate

     

     

    CPop3Connection::Connect

    BOOL CPop3Connection::Connect(LPCSTR pszHostName, LPCSTR pszUser,   LPCSTR pszPassword, int nPort = 110);

    Return Value

    If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.

    Parameters

    pszHostName The network address of the socket to connect to: a machine name such as “mail.yourisp.com”, or a dotted number such as “128.56.22.8”.

    pszUser This is the POP3 user name of the mailbox.

    pszPassword This is the password for the POP3 mailbox.

    nPort This is the port number on which to connect. The default value is 110 which is the default POP3 port number.

    Remarks

    Call this member function to establish a connection to a POP3 mailbox.

    See Also

    CPop3Connection::Disconnect

     

    CPop3Connection::Disconnect

    BOOL CPop3Connection::Disconnect();

    Return Value

    If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.

    Parameters

    None.

    Remarks

    The corollary function of Connect.

    See Also

    CPop3Connection::Connect

     

    CPop3Connection::Statistics

    BOOL CPop3Connection::Statistics(int& nNumberOfMails, int& nTotalMailSize);

    Return Value

    If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.

    Parameters

    nNumberOfMails Upon a successful return this will contain the number of mails waiting in the mailbox.

    nTotalMailSize Upon a successful return this will contain the size in bytes (aka Octets) of all mails waiting in the mailbox.

    Remarks

    Retrieves the statistics for the Mailbox by issuing the "STAT" command.

    See Also

    CPop3Connection::GetMessageSize

     

    CPop3Connection::Delete

    BOOL CPop3Connection::Delete(int nMsg);

    Return Value

    If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.

    Parameters

    nMsg The message number of the message to delete. This value starts at 1.

    Remarks

    Marks a message as "to be deleted" by issuing the "DELE" command.

    See Also

    CPop3Connection::Reset

     

    CPop3Connection::GetMessageSize

    BOOL CPop3Connection::GetMessageSize(int nMsg, DWORD& dwSize);

    Return Value

    If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.

    Parameters

    nMsg The message number of the message to retrieve the size of.

    dwSize Upon a successful return this will contain the size in bytes of the specified message.

    Remarks

    Retrieves the size of a specified message. Internally this will issue the "LIST" command if required.

    See Also

    CPop3Connection::Retrieve

     

    CPop3Connection::GetMessageID

    BOOL CPop3Connection::GetMessageID(int nMsg, CString& sID);

    Return Value

    If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.

    Parameters

    nMsg The message number of the message to retrieve the ID of.

    sID Upon a successful return this will contain the ID of the specified message as a string.

    Remarks

    Retrieves the ID of a specified message. Internally this will issue the "UIDL" command if required. As "UIDL" is an optional POP3 command, your client app should handle the return value if it is to correctly work on all POP3 servers.

    See Also

    CPop3Connection::UIDL

     

    CPop3Connection::Retrieve

    BOOL CPop3Connection::Retrieve(int nMsg, CPop3Message& message);

    Return Value

    If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.

    Parameters

    nMsg The message number of the message to retrieve the size of.

    message Upon a successful return this will contain the POP3 messages.

    Remarks

    Retrieves the specified message by issuing the "RETR" command.

    See Also

    CPop3Connection::GetMessageSize

     

    CPop3Connection::GetMessageHeader

    BOOL CPop3Connection::GetMessageHeader(int nMsg, CPop3Message& message);

    Return Value

    If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.

    Parameters

    nMsg The message number of the message to retrieve the header of.

    sID Upon a successful return this will contain the POP3 messages.

    Remarks

    Retrieves the header of a specified message. Internally this will issue the "TOP" command if required. As "TOP" is an optional POP3 command, your client app should handle the return value if it is to correctly work on all POP3 servers.

    See Also

    CPop3Connection::GetMessage

     

    CPop3Connection::Reset

    BOOL CPop3Connection::Reset();

    Return Value

    If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.

    Parameters

    None.

    Remarks

    Resets all messages which were previously marked as deleted. i.e. it undoes the work of all the DELE commands in this session. For further information about how messages are deleted in POP3, please refer to the RFC.

    See Also

    CPop3Connection::Delete

     

    CPop3Connection::UIDL

    BOOL CPop3Connection::UIDL();

    Return Value

    If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.

    Parameters

    None.

    Remarks

    Sends the "UIDL" command which retrieves the ID for a specified message. As "UIDL" is an optional POP3 command, your client app should handle the return value if it is to correctly work on all POP3 servers.

    See Also

    CPop3Connection::GetMessageID

     

    CPop3Connection::Noop

    BOOL CPop3Connection::Noop();

    Return Value

    If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.

    Parameters

    None.

    Remarks

    Issues a "NOOP" command to the server.

     

    CPop3Connection::GetLastCommandResponse

    CString CPop3Connection::GetLastCommandResponse() const;

    Return Value

    The last command response from the server as a CString.

    Parameters

    None.

    Remarks

    The CPop3Connection class can return additional text information along with most errors. This extended error information can be retrieved by using the GetLastCommandResponse function after an unsuccessful function call. An example of this is if the Connect function failed because of a validation problem, GetLastCommandResponse could return something like "-ERR Access is denied". GetLastCommandResponse can be called multiple times until another CPop3Connection function is called which sends a POP3 command.

     

    CPop3Connection::GetTimeout

    DWORD CPop3Connection::GetTimeout() const;

    Return Value

    The timeout in milliseconds which the code will wait for responses from the POP3 server.

    Parameters

    None.

    Remarks

    Since CPop3Connection provides a synchronous API, a timeout mechanism is provided. By default the value is 2 seconds in release mode and 20 seconds in debug mode. The value is larger in debug mode so that the code does not time out when you are debugging it.

    See Also

    CPop3Connection::SetTimeout

     

    CPop3Connection::SetTimeout

    void CPop3Connection::SetTimeout(DWORD dwTimeout) const;

    Return Value

    None.

    Parameters

    dwTimeout The new timeout value in milliseconds.

    Remarks

    Sets the timeout to use for connections to the POP3 server.

    See Also

    CPop3Connection::GetTimeout

     

     

    CPop3Message::GetMessageText

    LPCSTR CPop3Message::GetMessageText() const;

    Return Value

    A character pointer to the actual message text this class instance represents.

    Parameters

    None.

    Remarks

    Upon a successful call to CPop3Connection::Retrieve, the message class will contain a message. This function allows the text to of the message to be accessed.

    See Also

    CPop3Connection::Retrieve

     

    CPop3Message::GetHeader

    CString CPop3Message::GetHeader() const;

    Return Value

    A CString containing the header of this message

     

    CPop3Message::GetBody

    CString CPop3Message::GetBody() const;

    Return Value

    A CString containing the body of this message

     

    CPop3Message::GetHeaderItem

    CString CPop3Message::GetHeaderItem(const CString& sName, int nItem = 0) const;

    Return Value

    A CString containing the header body of the header field

    Remarks

    This function allows a specific message header line to be retrieved e.g you could call the function with sName set to "Date" to find the date the mail message was sent at. The return value is a CString which follows the internet convention for that particular header. The nItem parameter allows you to specify that the n'th occurrence of the header field be returned.

     

    CPop3Message::GetReplyTo

    CString CPop3Message::GetReplyTo() const;

    Return Value

    A CString containing the Reply to field

    Remarks

    Returns the most appropriate address for replies. Looks first for Reply-To, then From, then Sender, then Return-Path as a last resort, returns the first one of the above that is non-empty.

     

    CPop3Message::GetRawBody

    LPCSTR CPop3Message::GetRawBody() const;

    Return Value

    A const char pointer to the raw message body

     

    CPop3Message::GetSubject

    CString CPop3Message::GetSubject() const;

    Return Value

    A CString containing the subject of the message

    Remarks

    Returns the subject of the message.

     

    CPop3Message::GetFrom

    CString CPop3Message::GetFrom() const;

    Return Value

    A CString containing the sender of the message

    Remarks

    Returns the sender of the message.

     

    CPop3Message::GetDate

    CString CPop3Message::GetDate() const;

    Return Value

    A CString containing the "Date:" header of the message

    Remarks

    Returns the "Date:" header of the message.

    Planned Enhancements

    • Implement support for the APOP command.
    • Package the code up into an OCX, COM Interface or DLL to allow non MFC apps to use the code.
    • Provide a better sample app. At the moment, it's very much a test program which tests all of the functions.
    • If you have any other suggested improvements, please let me know so that I can incorporate them into the next release.
    Please send any comments or bug reports to me via email. For any updates to this article, check my site here.

    License

    This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

    A list of licenses authors might use can be found here

    Share

    About the Author

    PJ Naughter

    United States United States
    No Biography provided

    Comments and Discussions

     
    GeneralMy vote of 5 PinmemberAlbert van Peppen27-Jul-12 0:28 
    GeneralMy vote of 5 Pinmemberjacksp25-Nov-10 21:15 
    GeneralI try to connect Gmail. but i does not connect gmail... Pinmembervicky000008-Nov-09 18:58 
    SuggestionRe: I try to connect Gmail. but i does not connect gmail... PinmemberAlbert van Peppen20-Jun-12 22:10 
    GeneralError on compiling POP3.cpp PinmemberMSS-Software20-Dec-06 11:22 
    QuestionHow get the attachment in eml PinmemberTigerzjxjwb17-May-06 10:19 
    AnswerRe: How get the attachment in eml Pinmemberpjnaughter18-Jul-06 7:04 
    GeneralStack around the variable 'sBuf' was corrupted Pinmemberpro21-Sep-04 4:13 
    GeneralRe: Stack around the variable 'sBuf' was corrupted Pinmemberpjnaughter21-Sep-04 12:19 
    GeneralRe: Stack around the variable 'sBuf' was corrupted Pinmemberpro21-Sep-04 13:01 
    Questionhow to decode the attachments Pinmemberanukutty11-Apr-04 1:23 
    AnswerRe: how to decode the attachments Pinmemberpjnaughter11-Apr-04 3:38 
    GeneralRe: how to decode the attachments PinmemberTemp8318-Feb-06 6:43 
    GeneralRe: how to decode the attachments Pinmemberpjnaughter18-Feb-06 6:49 
    Generalplease update the source files!! PinsussAnonymous5-Oct-03 7:44 
    GeneralRe: please update the source files!! Pinmemberpjnaughter5-Oct-03 7:58 
    GeneralRe: please update the source files!! PinsussAnonymous5-Oct-03 9:58 
    GeneralVery useful! PinmemberThomas Latuske7-Mar-03 12:08 
    GeneralRe: Very useful! Pinmemberdragomir5-Jan-06 3:18 
    GeneralOrder By (mails) PinmemberAnonymous30-Jun-02 22:33 
    GeneralRe: Order By (mails) Pinmemberpjnaughter5-Oct-03 7:59 
    GeneralNot compilling :( PinmemberKaravaev Denis16-Jan-02 23:40 
    GeneralRe: Not compilling :( PinmemberPhil Gengler29-May-02 6:27 
    GeneralRe: Not compilling :( Pinmemberpjnaughter25-Sep-02 23:21 
    GeneralA bug , can't read text of body ,when have a attachment in it Pinmembercrossrainy16-Dec-01 15:39 
    GeneralRe: A bug , can't read text of body ,when have a attachment in it PinsussAnonymous25-Sep-02 22:39 
    GeneralRe: A bug , can't read text of body ,when have a attachment in it Pinmemberpjnaughter25-Sep-02 23:22 
    GeneralDamnit PinmemberAnonymous19-Aug-01 19:21 
    GeneralRe: Damnit PinmemberAnonymous19-Aug-01 20:57 
    GeneralError PinmemberAnton Okolelov24-Jun-01 12:30 
    GeneralRe: Error PinmemberAnonymous15-Aug-01 5:05 
    GeneralNew or Unread Messages PinmemberSateesh23-May-01 11:30 
    GeneralDoes not strip extra termination character PinmemberHedgehog14-Mar-01 5:54 
    GeneralMIME ++ PinsussAlpesh Makwana11-May-00 22:25 
    GeneralRe: MIME ++ Pinmemberharlie2-Dec-02 16:38 
    GeneralRe: MIME ++ Pinmemberharlie2-Dec-02 16:46 
    GeneralAbout EMail Attatched Files PinsussMichael Chen7-May-00 6:10 
    GeneralAbout EMail Attatched Files PinsussMichael Chen7-May-00 6:10 
    QuestionHow can read attached file? PinsussJeanie Moors18-Apr-00 17:59 
    AnswerRe: How can read attached file? PinsussPJ Naughter19-Apr-00 12:27 
    GeneralRe: How can read attached file? PinmemberMiguel Angel Diez2-Apr-01 5:53 
    Questiondelete mail in Pop3? Pinsussmazinga18-Apr-00 3:09 
    AnswerRe: delete mail in Pop3? PinsussPJ Naughter18-Apr-00 3:25 
    GeneralRe: delete mail in Pop3? PinsussFidel Davila Villagomez2-Nov-00 0:36 
    GeneralRe: delete mail in Pop3? PinmemberMauro20-May-01 9:40 
    GeneralRe: delete mail in Pop3? PinmemberMauro20-May-01 12:25 

    General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

    Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

    | Advertise | Privacy | Terms of Use | Mobile
    Web04 | 2.8.141223.1 | Last Updated 4 Mar 2000
    Article Copyright 2000 by PJ Naughter
    Everything else Copyright © CodeProject, 1999-2014
    Layout: fixed | fluid