20.7 Mail Retrieval: Using the POP3 Client

The next example program provides basic POP3 command access. After making a successful connection to an intended POP3 server and completing login transactions, the program checks for any pending messages in a mail box. If there is at least one message, the first message in the mail drop is retrieved and displayed on the screen.

20.7.1 Code and Explanation

Here is a portion of code followed by comments explaining key lines.

RWIPop3Reply reply;
RWIPop3StatReply statReply;
RWIPop3ConnReply connReply;

try {
  RWIPop3Client client;                                    // 1
  connReply = client.connect("mail.roguewave.com");        // 2
  reply = client.user("user");                             // 3
  reply = client.pass("password");                         // 4

  statReply = client.stat();                               // 5
  int totalMsgs = statReply.messages();                    // 6
  cout << "The number of messages is : << totalMsgs << endl;

  if (totalMsgs > 0) {
    cout << "Let's retrieve the first message." << endl;
    dataReply = client.retr(1);                            // 7
    
    if (!dataReply.isErr()) {                              // 8
      RWSocketPortal portal = dataReply.portal();          // 9
      RWPortalIStream istr(portal);                        //10
      RWCString line;

      do {
        line.readLine(istr);                               //11
        line = rwNormalizeLine(line);                      //12

        if (line != ".") {
          cout << line << endl;
        }
      } while (line != ".");                               //13
    }
  }
}
catch (const RWxmsg& msg) {                                //14
  cout << "ERROR: " << msg.why() << endl;
}

`//1`	Constructs an *RWIPop3Client* object. The object is set to an unconnected state, ready to use the `connect()` method of *RWIPop3Client* to establish a connection with a POP3 server. When the object goes out of scope, disconnection from the server is automatic.
`//2`	Establishes a connection with a POP3 server of interest.
`//3`	Performs the `USER` protocol command.
`//4`	Performs the `PASS` protocol command.
`//5`	Performs the `STAT` protocol command.
`//6`	Gets the total number of pending messages in the mail drop, via the `messages()` method invocation on the returned `statReply` object of class *RWIPop3StatReply*.
`//7`	Performs the `RETR` protocol command, and immediately redeems the result as the *RWIPop3DataReply* object `dataReply`, which contains a socket portal to complete the data portion of the protocol transfer.
`//8`	Checks whether the data reply is `+OK`. A successful reply from the `retr()` method is normally `+OK`, which indicates that the data connection has been opened.
`//9`	Gets the data socket portal from the `dataReply` object to retrieve data from the underlying socket.
`//10`	Creates an *RWPortalIStream* object `istr` built from the socket portal available from `//9`. The object `istr` becomes the data source.
`//11`	Reads one line of the mail data at a time.
`//12`	Removes the line feed at the end of the line.
`//13`	Reads message data until a period is contained in a line by itself, which is the indication of the end of a mail message.
`//14`	This `catch` clause catches all the `int` library, the `net` library, and Threads.h++ exceptions that can be thrown from within the `try` block, since all Rogue Wave exceptions are derived from *RWxmsg*.

20.7.2 Further Discussion

This example demonstrates one method of redeeming an RWIOUResult object. For other methods, please refer to Chapter 19 and Section 20.4. The application determines which way needs to apply.