Pop3Client provides a member function Connect() to connect to a POP3 server and other member functions to send POP3 commands to the server. Each of these member functions returns 0 if the client received a response from the server, and -1 if it did not. In other words, a 0 return value indicates that the client and server communication succeeded; a -1 return value usually indicates that a network error occurred. It is important to remember, however, that these member functions return 0 even in the case that the server failed to execute the command -- that is, the server sent an -ERR response. You should also call the member function ReplyCode() to get the server's reply code, which indicates if the server successfully executed the POP3 command.
To use Pop3Client, first call the Connect() member function to connect to the POP3 server. If the Connect() member function succeeds, then you may call other member functions to send POP3 commands to the server. After you send a command, you should check the function's return value. A zero return value indicates that the server received the client's command, and that the client received the server's response. A non-zero value indicates that the communication between client and server failed. Next, you should call the ReplyCode() member function to learn if the command succeeded at the server. The reply code Pop3Client::OK indicates success. The reply code Pop3Client::ERR indicates failure. For some commands, such as for the DELE command, the server returns information in a single-line response. You may call the ReplyText() member function to get the server's single-line response. For other commands, such as for the RETR command, the server returns information in a mulitple-line response. For these commands, the library passes each line of the server's response to a listener object you implement. Your listener object must be a subclass of ProtocolListener. You must call the SetListener() member function to install your listener object. After you have sent all the POP3 commands you need, you should call the Disconnect() member function to disconnect from the server.
You should examine the return values of the member functions to detect communication errors. If a member function returns -1, which indicates that an error occurred, you may call other member functions to get the details of the error. You may call ErrorCode() to get a platform-independent error code. You may call OsErrorCode() to get the error code that was reported by the operating system. You may call ErrorMessage() to get a text error message that you can write to a log file.
One advanced feature of Pop3Client is the ability to cancel a network operation. For example, if you are developing an interactive application with a user interface, you may allow the user to cancel a network operation that has stalled or that is taking too much time. To provide this capability, Pop3Client provides a Cancel() member function that you may call from your user interface thread, which is a different thread from the thread that is controlling the POP3 connection.
Public Member Functions | |
| Pop3Client () | |
| Default constructor. | |
| virtual | ~Pop3Client () |
| Destructor. | |
| void | SetTraceOutput (TraceOutput *out, bool takeOwnership) |
| Sets a Trace Output instance. | |
| void | SetTimeout (int secs) |
| Sets the timeout value for network send and receive operations. | |
| void | SetReceiveTimeout (int secs) |
| Sets the timeout value for network receive operations. | |
| void | SetSendTimeout (int secs) |
| Sets the timeout value for network send operations. | |
| void | SetListener (ProtocolListener *listener, bool del) |
| Sets the listener object to process multiple line responses. | |
| void | Cancel () |
| Cancels a currently executing command. | |
| int | Connect (const char *address, int port=110, bool wait=true) |
| Opens a connection to a POP3 server. | |
| int | ConnectTls (const char *serverHostName, bool wait=false) |
| Opens a TLS connection over an existing TCP connection. | |
| int | ConnectTlsOpenSSL (const char *serverHostName, void *ssl, bool wait=false) |
| Establishes a TLS connection over an existing TCP connection. | |
| void | Disconnect () |
| Disconnects from the server. | |
| int | Capa () |
| Sends the CAPA command. | |
| int | Stls () |
| Sends the STLS command. | |
| int | User (const char *user) |
| Sends the USER command. | |
| int | Pass (const char *password) |
| Sends the PASS command. | |
| int | Apop (const char *user, const char *password) |
| Sends the APOP command. | |
| int | Auth (const char *mechanism) |
| Sends the AUTH command. | |
| int | AuthCramMd5 (const char *user, const char *password) |
| Send the AUTH CRAM-MD5 command. | |
| int | AuthNtlm (const char *user, const char *password) |
| Send the AUTH NTLM command. | |
| int | Stat () |
| Sends the STAT command. | |
| int | List () |
| Sends the LIST command. | |
| int | List (int msgNum) |
| Sends the LIST command with a message number argument. | |
| int | Retr (int msgNum) |
| Sends the RETR command. | |
| int | Dele (int msgNum) |
| Sends the DELE command. | |
| int | Top (int msgNum, int numLines) |
| Sends the TOP command. | |
| int | Uidl () |
| Sends the UIDL command. | |
| int | Uidl (int msgNum) |
| Sends the UIDL command with a message number argument. | |
| int | Noop () |
| Sends the NOOP command. | |
| int | Rset () |
| Sends the RSET command. | |
| int | Quit () |
| Sends the QUIT command. | |
| int | ReplyCode () const |
| Gets the server's reply code. | |
| const char * | ReplyText () const |
| Gets the text of the server's reply. | |
| Error | ErrorCode () const |
| Gets the platform-independent error code for the last error. | |
| int | OsErrorCode () const |
| Gets the platform-specific error code for the last error. | |
| const char * | ErrorMessage () const |
| Gets the error message for the last error. | |
|
|
Default constructor. |
|
|
Destructor. The destructor performs all necessary clean-up, including closing the connection to the server if it is not already closed. |
|
||||||||||||
|
Sends the APOP command. The APOP command authenticates a user to the POP3 server. The APOP command is an alternative to the USER and PASS command sequence for client authentication. APOP is more secure than USER and PASS because it does not send the user's password over the network to the server. If the server supports APOP, you should use APOP instead of USER and PASS. APOP is an optional command that is not supported by all servers. If the server does not support APOP, this member function responds in one of two different ways:
|
|
|
Sends the AUTH command. You may use this member function to send an AUTH command with the parameters you specify. For AUTH CRAM-MD5 authentication, you should use the AuthCramMd5() member function. For AUTH NTLM authentication, you should use the AuthNtlm() member function.
|
|
||||||||||||
|
Sends the AUTH CRAM-MD5 command. The AUTH CRAM-MD5 command authenticates a user to the POP3 server. The AUTH CRAM-MD5 command is similar to the APOP command, in that it does not send the user's password over the network. AUTH CRAM-MD5, however, is one of a standard set of authentication protocols defined by SASL, and it is used in other protocols such as IMAP4 and ESMTP. The server's response to the AUTH CRAM-MD5 command indicates success or failure. To check for success, call the ReplyCode() member function.
|
|
||||||||||||
|
Sends the AUTH NTLM command. The AUTH NTLM command authenticates a user to the POP3 server. The AUTH NTLM command is similar to the APOP command, in that it does not send the user's password over the network. AUTH NTLM, however, is one of a standard set of authentication protocols defined by SASL, and it is used in other protocols such as IMAP4 and ESMTP. The NTLM authentication mechanism is used to authenticate users in a Microsoft Windows environment. It is a popular option for authentication with Microsoft Exchange Server. The server's response to the AUTH NTLM command indicates success or failure. To check for success, call the ReplyCode() member function.
|
|
|
Cancels the currently executing command. Since it is possible for a network connection to stop responding, an interactive application must be able to cancel a command that is waiting on a network operation (connect, send, or receive). For this reason, the Pop3Client class provides a Cancel() member function, which promptly terminates any currently executing client command. Cancel() is the only member function that is safe to call from another thread. In a typical situation, you have one thread that executes POP3 commands, and another thread that serves the user interface. A user action to cancel is serviced by the user interface thread, which calls Cancel() on the Pop3Client object to cancel a command. The command function that the POP3 client thread was executing at the time may return an error. (It will return an error if the cancel operation occurred before the command was completed.) Because it is difficult to recover the client/server state after a cancel operation, the library closes the connection whenever you call the Cancel() member function. You must call Connect() again to reconnect to the POP3 server. Note: You should not call the Connect() function from the same thread thread that called Cancel().
|
|
|
Sends the CAPA command. The CAPA command gets a list of the server's capabilities -- that is, a list of optional features that the server supports. If the function's return value is zero, you should call the ReplyCode() member function to learn if the command succeeded at the server. If the command succeeds, the server sends a multiple-line response. To get the list of server capabilities, you must call SetListener() to install a listener object before you call Capa(). The Pop3Client object passes the lines of the multiple-line response, except for the first "status" line, to your ProtocolListener object. Each line of the response contains a keyword that indicates an optional feature supported by the server.
|
|
||||||||||||||||
|
Opens a connection to a POP3 server. This member function opens a connection to the host at network address address and TCP port port. The address parameter may be either a hostname, such as "pop3.example.com", or an IP address in dotted decimal form, such as "192.168.2.25". The default value for port is 110, the well-known TCP port number for POP3. If the client connects to the server successfully, then Connect() returns 0. If the client fails to connect to the server -- for example, if the host is not found or some other network error occurs -- then Connect() returns -1. If Connect() returns 0, then you should call the ReplyCode() member function to check the server's reply code. The server sends a Pop3Client::OK reply code if it is ready to process commands. You may call the Cancel() member function from another thread to cancel this operation. If the optional parameter wait is true, it causes the client to wait for the server's greeting. In the POP3 protocol, the server always begins the dialog with its initial greeting. However, if you need to establish a TLS connection to the server, you may set wait to false. Then, the function returns immediately after the TCP connection is established without waiting for the server's initial greeting.
|
|
||||||||||||
|
Opens a TLS connection over an existing TCP connection. Transport Layer Security (TLS) provides server authentication and private communication over a TCP connection. TLS is the successor to Secure Sockets Layer (SSL), and individuals often use the term SSL even if the actual protocol is TLS. TLS is a standards track protocol developed by the IETF and described in RFC 2246. Before you call ConnectTls(), you must have established a TCP connection to the server. You must also have configured the TlsConfig object. Normally, you configure the TlsConfig object when you initialize your application. ConnectTls() starts a dialog between client and server, called a TLS handshake, to negotiate security parameters for the secure connection and to authenticate the server. If the handshake succeeds, a secure TLS connection is established between client and server. During the TLS handshake, the server sends a certificate to the client, and the client examines the certificate to verify the identity of the server. The certificate must be valid, and it must contain the host name of the server. When you call ConnectTls(), you provide the server's host name in the serverHostName parameter. The library tries to match serverHostName with the host name in the certificate. If the match fails, but the handshake otherwise succeeds, then the function returns -1, and the error code is BAD_CERTIFICATE_NAME_ERROR. In many applications, a BAD_CERTIFICATE_NAME_ERROR is not automatically treated as a fatal error; rather, the application presents an alert to the user and allows the user the choice to abort the connection or to continue and ignore the failure. Therefore, BAD_CERTIFICATE_NAME_ERROR should be treated as a severe warning: the server authentication failed but the secure connection succeeded. You should treat any other error that occurs during the handshake as a fatal error and close the TCP connection. If the optional parameter wait is true, it causes the client to wait for the server's greeting. It is important to set the correct value for this parameter. There are two cases: In the first case, you call Connect() to connect to a special secure POP3 port (TCP port 995) and then immediately call ConnectTls() to create a TLS connection. In this case, you call Connect() with wait false and you call ConnectTls() with wait true. In the second case, you call Connect() to connect to the standard POP3 port (TCP port 110). Then you call Stls() to indicate to the server that you want to begin a TLS handshake. Then you call ConnectTls() create a TLS connection. In this case, you call Connect() with wait true (the default), and you call ConnectTls() with wait false (also the default). The function returns 0 on success and -1 on failure. To check the error code after a failure, call ErrorCode().
|
|
||||||||||||||||
|
Opens a TLS connection over an existing TCP connection, using a specified SSL struct. For simple use of TLS, you may use the ConnectTls() member function. For advanced use, you may use this member function, which allows you to create an SSL struct and pass it to the library to use. Examples of situations where you may choose to use the ConnectTlsOpenSSL() function include:
To use ConnectTlsOpenSSL(), you must call the OpenSSL function SSL_new(SSL_CTX*) to create an SSL struct. After you configure the SSL struct, you pass it as the ssl parameter to ConnectTlsOpenSSL(). The Pop3Client destructor calls SSL_free(SSL*) to free the SSL struct. However, OpenSSL uses a reference counting mechanism, and you may use that mechanism to prevent the Pop3Client destructor from freeing the SSL struct. To prevent the Pop3Client's destructor from freeing the SSL struct, increment the reference count before you pass the struct to the Pop3Client, like so:
CRYPTO_add(&ssl->references, 1, CRYPTO_LOCK_SSL);
|
|
|
Sends the DELE command. The DELE command causes the server to mark a message for deletion. The server does not actually delete the message until (and unless) the client sends the QUIT command to close the mailbox properly. The server's response to the DELE command indicates success or failure. To check for success, call the ReplyCode() member function.
|
|
|
Closes the connection to the POP3 server. The correct way to end a POP3 session is to send a QUIT command, which causes the server to perform any necessary closing operations and close the connection. Therefore you should almost always call Quit() immediately before you call Disconnect(). You may safely call this method even if the client is not connected.
|
|
|
Gets the platform-independent error code for the last error. The error codes are enumerated in the file mailpp/Error.h. Note that they are defined in the mailpp namespace. The ErrorMessage() member function returns a textual description of the platform-independent error. If the error code is SYSTEM_ERROR, you may call OsErrorCode() to get more detailed information about the error.
|
|
|
Gets the error message for the last error. This function returns a textual description of the platform-independent error code.
|
|
|
Sends the LIST command with a message sequence number argument. The LIST command with a message sequence number argument gets the size of the specified message. The server's response is a single line reply. To check for success, call the ReplyCode() member function. To get the size of the specified message, call the ReplyText() member function. The reply text string contains the message sequence number, a space character, and the size of the message in bytes.
|
|
|
Sends the LIST command with no argument. The LIST command with no argument gets a list of all the messages in the mailbox. Each item in the list contains a message sequence number and the size of the message. If the function's return value is zero, you should call the ReplyCode() member function to learn if the command succeeded at the server. If the command succeeds, the server sends a multiple-line response. To get the list of messages, you must call SetListener() to install a listener object before you call List(). The Pop3Client object passes the lines of the multiple-line response, except for the first "status" line, to your ProtocolListener object. Each line contains a message sequence number, a space character, and the size of the message in bytes.
|
|
|
Sends the NOOP command. The server takes no action in response to a NOOP command except to send a positive response. (NOOP means "no operation".) A POP3 client may send the NOOP command to reset a connection timeout timer at the server. The return value indicates if the communication between client and server was successful. The server always responds with a Pop3Client::OK reply code to the NOOP command.
|
|
|
Gets the platform-specific error code for the last error. This function gets the error code reported by the operating system. The operating system's error code is necessarily platform-specific. This error code is probably not as useful as the platform-independent error code, but it might provide information helpful for debugging. The operating system's error code provides more specific information when the platform-independent error code is SYSTEM_ERROR. Not all errors have an operating system error code. Some errors, such as library usage errors, are detected in the Hunny Mail++ library itself.
|
|
|
Sends the PASS command. The PASS command sends the user's password to the server. Before you send the password, you must send the USER command to send the login name for that user. If the function's return value is zero, you should call the ReplyCode() member function to learn if the command succeeded at the server.
|
|
|
Sends the QUIT command. The QUIT command causes the server to delete any messages from the mailbox that were marked for deletion (by the DELE command), and then close the connection.
|
|
|
Gets the reply code of the server's response to the most recent command. Two reply codes are possible: the reply code Pop3Client::OK indicates success; the reply code Pop3Client::ERR indicates failure. (These enum values are the ASCII values of the actual error codes: Pop3Client::OK == '+', Pop3Client::ERR == '-'.)
|
|
|
Gets the reply text of the server's response to the most recent command. The ReplyText() member function removes the initial success or failure indication and the final CR LF from the server's response. For example, if the server's response is "+OK User okay\\r\\n", the reply text is "User okay". If the server's response is "-ERR User unknown\r\n", the reply text is "User unknown". If the server sends a multiple line response, this member function returns only the text of the first line (the status line).
|
|
|
Sends the RETR command. The RETR command retrieves a complete message from the POP3 server. The RETR command takes one argument. The argument is the sequence number of the message to retrieve. If the function's return value is zero, you should call the ReplyCode() member function to learn if the command succeeded at the server. If the command succeeds, the server sends a multiple-line response. To get the content of the message, you must call SetListener() to install a listener object before you call Retr(). The Pop3Client object passes the lines of the multiple-line response, except for the first "status" line, to your ProtocolListener object. Each line of the response contains one line of the message.
|
|
|
Sends the RSET command. The RSET command resets the server to its initial state. The server "unmarks" any messages that were marked for deletion (by the DELE command). The server's response to the RSET command indicates success or failure. To check for success, call the ReplyCode() member function.
|
|
||||||||||||
|
Sets the listener object for this Pop3Client object. The listener object receives the lines of a multiple-line response as the client receives them. The server sends a multiple-line response for these commands: CAPA, LIST (with no argument), RETR, TOP, and UIDL (with no argument). The final line, which contains a dot ('.') by itself, is not passed to the listener object. You may use one ProtocolListener object to receive the lines from many responses. Typically, you create a Pop3Client object, create a listener object, and call SetListener() only once to install the listener object. Then you use the same listener object for the lifetime of the Pop3Client object.
If del is true, the Pop3Client object's destructor calls
|
|
|
Sets the timeout for network receive operations. The library supports separate timeout values for sending and receiving. This property affects the timeout for receive operations. The send timeout property affects the timeout for connect and send operations. If a network operation times out, the member function that was executing returns -1, and ErrorCode() returns TIMED_OUT_ERROR.
|
|
|
Sets the timeout for network send operations. The library supports separate timeout values for sending and receiving. This propery affects the timeout for connect and send operations. The receive timeout property affects the timeout for receive operations. If a network operation times out, the member function that was executing returns -1, and ErrorCode() returns TIMED_OUT_ERROR.
|
|
|
Sets the timeout value for network send and receive operations. The timeout applies to these network operations: connect, receive, and send. If a network operation times out, the member function that was executing returns -1, and ErrorCode() returns TIMED_OUT_ERROR. This member function is deprecated. Use SetReceiveTimeout() and SetSendTimeout() to set network timeouts.
|
|
||||||||||||
|
Sets a TraceOutput instance. When you set a TraceOutput instance, you enable trace output, which may be helpful for debugging. You may set a null value to disable trace output. The Hunny Mail++ library provides a StdTraceOutput class that prints all output to standard output. If you pass a true value for the takeOwnership parameter, then the Pop3Client object has the responsibility to delete the trace output object. On the other hand, if you pass false, then your code must delete the trace output object when it is no longer needed.
|
|
|
Sends the STAT command. The STAT command gets the status of the mailbox. The status report includes the number of messages in the mailbox and the combined number of bytes in the mailbox. The server's response to the STAT command is a single line reply. To check for success, call the ReplyCode() member function. To get the number of messages and the number of bytes in the POP3 mailbox, call the ReplyText() member function.
|
|
|
Sends the STLS command. The STLS command asks the server to begin a TLS handshake. If the STLS command succeeds, as indicated by a +OK reply from the server, then you should immediately call ConnectTls() to start the TLS handshake and to establish the secure connection. The STLS POP3 command is documented in RFC 2595. Note: You must have Secure Mail++ to use this member function. In (non-Secure) Mail++, the function returns -1.
|
|
||||||||||||
|
Sends the TOP command. The TOP command retrieves only the first part of a message. The command takes two arguments. The first argument is the sequence number of a message in the POP3 mailbox. The second argument is the number of lines of the message body that the client wants to retrieve. If the function's return value is zero, you should call the ReplyCode() member function to learn if the command succeeded at the server. If the command succeeds, the server sends a multiple-line response. To get the lines of the message, you must call SetListener() to install a listener object before you call Top(). The Pop3Client object passes the lines of the multiple-line response, except for the first "status" line, to your ProtocolListener object. Each line of the response contains one line of the message.
|
|
|
Sends the UIDL command with a message sequence number argument. The UIDL command gets a unique ID listing for one or more messages. If the command has a message sequence number argument, then the server sends a unique ID listing for that message. If the command has no argument, then the server sends a unique ID listing for every message in the POP3 mailbox. This function sends a UIDL command with a message sequence number argument. The server's response is a single line reply. To check for success, call the ReplyCode() member function. To get the size of the specified message, call the ReplyText() member function. The reply text string contains the message sequence number, a space character, and the unique ID for the message.
|
|
|
Sends the UIDL command with no argument. The UIDL command gets a unique ID listing for one or more messages. If the command has a message sequence number argument, then the server sends a unique ID listing for that message. If the command has no argument, then the server sends a unique ID listing for every message in the POP3 mailbox. This function sends a UIDL command with no argument. If the function's return value is zero, you should call the ReplyCode() member function to learn if the command succeeded at the server. If the command succeeds, the server sends a multiple-line response. To get the lines of the unique ID listing, you must call SetListener() to install a listener object before you call Top(). The Pop3Client object passes the lines of the multiple-line response, except for the first "status" line, to your ProtocolListener object. Each line of the response contains a message sequence number, a space character, and the unique identifier for the message.
|
|
|
Sends the USER command. The USER command sends the user login name to the server. After you send the user name, you must send the PASS command to send the password for that user. If the function's return value is zero, you should call the ReplyCode() member function to learn if the command succeeded at the server.
|
Copyright © 2001-2005 Hunny Software, Inc. All rights reserved.