PHDEmail Component POP3 Object Interface

Last modified: 20 July 2001.

Home page
  • POP3 Object Interface
    Introduction
    Usage
    Errors
    PHDEmailTest example
    Properties
    Methods
    Message Encoding

  • Introduction

    The PHDPOP3 object in the PHDEmail COM component lets you read emails using POP3.  It runs in any COM programming language or container.

    Most people will use the PHDPOP3 object in an application that has to interrogate a server to read emails.  However you can also happily call it from an ASP script, or a Dynamic-CD GASP script.

    • Before using PHDPOP3, you must register the PHDEmail component, as described here.

    • Usage of the component Properties and Methods is illustrated by the PHDEmailTest C++ example.

    • You use PHDPOP3 by getting it to connect to your POP3 server.  Once the username and password have been verified, you can issue various commands to the server before quitting.  There are commands to list all the available messages, and retrieve or delete individual messages.

    Limitations

    • PHDPOP3 cannot receive emails from a web based email service.  PHDPOP3 cannot read messages from newsgroups.
    • PHDPOP3 currently cannot read file attachments.
    • The POP3 "APOP" and "NOOP" commands are not currently supported.

    Technical information

    The PHDPOP3 object interface Program ID is "PHDEmail.PHDPOP3".

    PHDEMail is an ANSI component, ie it works with 8-bit characters.  If you are running an application that sends non-ANSI characters to PHDEmail, then these will be received as question marks (?).  Characters read by your application will be converted to your code page as best as possible.

    See below for details of how message text is encoded.

    The Post Office Protocol 3 (POP3) defines one way to read emails over the net.  POP3 was originally defined in RFC 1460; the latest definition is in RFC 1939.  The email message format was originally defined in RFC 822; the latest definition is in RFC 2822.  Other RFCs define other aspects of message formatting.
    The IMAP protocol defines another way of reading and manipulating emails on a server
    Note that the SMTP protocol is usually used to send emails.


    Usage

    Do not forget to register the PHDEmail component first.

    In your chosen programming environment, create an instance of the "PHDEmail.PHDPOP3" object.  Then set the RemoteHostName, UserName and Password properties.  Call the ConnectToRemoteHost(), USER() and PASS() methods to connect to your POP3 server, identify the mailbox and authenticate yourself, not forgetting to check the return results from each method call.

    You will normally then call STAT() and inspect the single line in Response to determine the number of messages in the mailbox.  The number of messages will not change in this session if you mark a message for deletion using DELE().

    If you want, you can then set MessageNumber to zero and call LISTn() to get a multi-line response, with one line per available message containing its number and raw size in bytes.  Initially the message numbers will increment from 1 upwards.  However if you mark a message for deletion using DELE(), then that message number will not appear in future.  For example if you delete the third message of four available, a subsequent LISTn(0) will return lines with message numbers 1, 2 and 4.

    To read a message, set MessageNumber to the appropriate message number and call RETR().  The whole message is stored in Message and its constituent parts are extracted and put in MessageHeader, MessageBody, MessageDate, MessageSubject and MessageSender.
    The Response just contains the first POP3 response line usually starting with "+OK" or "-ERR".  See below for details of how message text is decoded.

    If you do not want to get all a message, then call TOPn() for the desired MessageNumber.  Give TOPn() a parameter indicating the number of lines of the message body that you want to receive, ie a number from zero upwards.  The header is always read.  All the same variables are set as for RETR(), with the MessageBody empty if the requested number of lines is zero.  Note that there is a chance that some older POP3 servers may not support TOPn().

    To delete a message, set the MessageNumber and call DELE().  The message will be marked for deletion and will not appear in a LISTn(0) listing.  However the message will only actually be deleted when a call to QUIT() completes successfully.

    When you have finished, call QUIT().  Your POP3 server will now delete any messages that you have marked for deletion using DELE().

    Errors

    All the PHDPOP3 methods return zero if successful.  This usually indicates that the POP3 server started its Response with the POP3 success indication "+OK".  For POP3 error indications starting "+ERR" and other PHDPOP3 detected errors, a negative value is returned.  Numbers greater than 10000 are communication errors, such as a timeout.  The file EmailErr.h in the development kit is a C++ header with definitions of the PHDEmail negative error values.

    The ErrorMsg read-only property contains a full description of the error.  The Response read-only property contains the last response line or lines obtained from your POP3 server.  Response may be an empty string.

    If you get timeout errors, then you might like to try increasing the values of the RecvTimeout and SendTimeout parameters.


    PHDEmailTest C++ Example

    The PHDEmailTest program shows how to access the PHDEmail PHDPOP3 object from C++.  See the main page for basic information about PHDEmailTest.

    The picture below shows the POP3 tab of PHDEmailTest in action.  The user has connected and got a list of messages.  Message 8 has been selected and retrieved.

    The PHDPOP3 interface has been imported into a class called IPHDPOP3, defined in PHDEmail.h and PHDEmail.cpp.  The main POP3 code is in the CPOP3Tab class, defined in POP3Tab.cpp and POP3Tab.h.  This code illustrates how to call PHDPOP3 and parse the Response return values.

    In the SMTP example, an IPHDSMTP instance was only used when the Send button was pressed.  In the POP3 code, the IPHDPOP3 instance (pointer m_pop3) is created when the CPOP3Tab class is created, ie when the program starts.  The instance is only deleted when the program exits.

    The code for the Connect button makes many PHDEmail PHDPOP3 calls.  It sets the RemoteHostName, UserName and Password properties, and then calls ConnectToRemoteHost(), USER() and PASS() to connect to the POP3 server.  Routine GetMessageList() calls STAT() to determine the total number of messages.  It then calls LISTn() to get a list of available message numbers.  For each available message, TOPn() is called to retrieve the message header.  This information is used to fill the message list box.

    Clicking on Disconnect results in a call to QUIT(); any messages marked for deletion are deleted if this call works.  Alternatively calling Abandon simply calls CleanupConnection() so that messages marked for deletion are NOT deleted.  Clicking on Exit is the same as calling Disconnect.

    Get Message retrieves the selected message using RETR()Delete Message marks the selected message for deletion using DELE(); the message list is refilled using GetMessageList().  Finally, Top Lines retrieves the top lines of the selected message using TOPn().

    Use of RSET() method is not illustrated.  If you call this, then any messages marked as deleted are undeleted.


    Properties

    Here is a complete list of the PHDEMail component PHDPOP3 object properties.  Those listed in a yellow background are advanced parameters that are not normally used.

    Property
    name
    Type Description Example
    ErrorMsg String
    read only
    A full description of the last error. PHDEmail: ConnectToRemoteHost Connection refused (10061)
    MailPort Long The TCP/IP port of the POP3 server to contact. Default is 110
    Message String The whole message, ie the MessageHeader and the MessageBody, stored by RETR() or TOPn().
    MessageBody String The main text of the email stored by RETR(), or the first lines of main text stored by TOPn().
    MessageDate String The message date, extracted from the MessageHeader, stored by RETR() or TOPn().
    MessageHeader String All the headers of the email, stored by RETR() or TOPn().
    MessageNumber Long The number of the message to read, usually from 1 upwards.
    Can be zero for the LISTn() method.
    1
    MessageSender String The message sender, extracted from the MessageHeader, stored by RETR() or TOPn().
    MessageSubject String The message subject, extracted from the MessageHeader, stored by RETR() or TOPn().
    Password String The authentication password. SecretFromYou
    RecvTimeout Long
    (seconds)
    The receive timeout in seconds. The default value is -1, ie:
    the "connect to host" time-out is 15 seconds.
    the "receive data" time-out is 10 seconds.
    Default is -1
    RemoteHostName String The domain name or IP address of the POP3 mail server to contact.
    Do not include www. in the domain name.
    mail.phdcc.com
    or
    192.168.0.1
    Response String
    read only
    The last response line sent by your POP3 server.  It should start with either "+OK" or "-ERR", and is usually followed by a text description.  The response may be several lines long.  See the POP3 specifications for details of all POP3 responses. 221 2.0.0 Service closing transmission channel
    SendTimeout Long
    (seconds)
    The send timeout in seconds.  The default value is -1, ie:
    the "send data" time-out is 2 seconds.
    Default is -1
    UserName String The authentication username. chris/example.org


    Methods

    Here is a complete list of the PHDEMail component PHDPOP3 object methods, ie functions.  Those listed in a yellow background are advanced methods that are not normally used.

    All methods set ErrorMsg and Response unless otherwise noted.

    Method
    name
    Parameters Return value Description
    CleanupConnection none None
    Does NOT set ErrorMsg or Response
    Closes the connection to the POP3 server cleanly.
    ConnectToRemoteHost none Long error code.
    Zero if OK.
    Attempts to connect to the POP3 server, with the domain name or IP address in RemoteHostName at the given MailPort

    If this call succeeds, then you should call QUIT() to close the conversation and connection cleanly.

    DELE none Long error code.
    Zero if OK.
    Marks the message denoted by MessageNumber for deletion.  The message is only deleted when QUIT() is called.
    Calling RSET() undeletes all messages marked for deletion.
    LISTn none Long error code.
    Zero if OK.
    If MessageNumber is zero, then this stores the multi-line Response indicating the number and size of each message.  Messages marked for deletion are not listed.

    If MessageNumber is a valid message number greater than zero, then this stores the single-line Response indicating the number and size of the message.  A message is marked for deletion is not valid and so an error is returned.

    PASS none Long error code.
    Zero if OK.
    Sends the Password to the POP3 server for authentication.
    QUIT none Long error code.
    Zero if OK.
    Closes the POP3 conversation and POP3 connection, deleting any messages that have been marked for deletion with DELE().  There is no need to call CleanupConnection() after this.
    RETR none Long error code.
    Zero if OK.
    Reads the whole message denoted by MessageNumber.  The whole message is stored in Message and its constituent parts are extracted and put in MessageHeader, MessageBody, MessageDate, MessageSubject and MessageSender.
    The Response just contains the first POP3 response line usually starting with "+OK" or "-ERR".
    RSET none Long error code.
    Zero if OK.
    Issues the reset command to the POP3 server.  This undeletes any messages that have been marked for deletion.
    STAT none Long error code.
    Zero if OK.
    Stores the single-line Response indicating the total number of message and the total size.
    TOPn Long BodyLineCount
    Must be >=0
    Long error code.
    Zero if OK.
    Reads the message header and <BodyLineCount> lines of the message body from message MessageNumber.  The whole text is stored in Message and its constituent parts are extracted and put in MessageHeader, MessageBody, MessageDate, MessageSubject and MessageSender.
    The Response just contains the first POP3 response line usually starting with "+OK" or "-ERR".

    Some POP3 servers may not support this command.

    USER none Long error code.
    Zero if OK.
    Sends the UserName to the POP3 server for authentication.


    Message Encoding

    Originally emails could only be 7-bit with very limited line lengths, ie 76-80 characters.  Various Internet RFC standards have been defined over the years to overcome these restrictions to let us send and receive whatever text and files we want in emails.  These standards specify how text and files should be encoded so that no information is lost.

    PHDPOP3 does not currently support the full gamut of email encodings.  However PHDPOP3 automatically recognises the Quoted-Printable encoding and decodes the MessageBody returned by the RETR() and TOPn() methods.  Note that the Message property is not decoded.  PHDPOP3 does nothing for all other encodings.


    PHDEmail online