Pop3Client::Pop3Client Class Reference

This class provides the interface to POP3 servers and supports optional TLS/SSL encryption. More...

## Public Member Functions

| clearStats ()
| Clears performance statistics. More...
nothing | clearWarningQueue ()
| Removes any warning Queue object from the Socket. More...
| connect ()
| Connect to the server with the connection parameters set in the constructor() More...
| constructor (string url, *code log, *code dbglog)
| creates the Pop3Client object More...
| del (softstring msg)
| sends a `"DELE"` command (http://tools.ietf.org/html/rfc1939#page-8) to the POP3 server to mark the given message as deleted More...
| del (list l)
| sends a `"DELE"` command (http://tools.ietf.org/html/rfc1939#page-8) to the POP3 server to mark the given message as deleted More...
| destructor ()
| disconnects if connected and destroys the object More...
| disconnect ()
| disconnect from the server More...
| forceDisconnect ()
| force disconnect of socket without error More...
date | getConnectTimeoutDate ()
| returns the connect timeout as a relative time value More...
int | getConnectTimeoutMs ()
| returns the connect timeout as an integer giving milliseconds More...
*hash | getMail ()
| returns a hash of mail messages keyed by message ID or NOTHING if no messages are available on the server More...
date | getReadTimeoutDate ()
| returns the read timeout as a relative time value More...
int | getReadTimeoutMs ()
| returns the read timeout as an integer giving milliseconds More...
string | getTarget ()
| Returns the connection target string. More...
hash< auto > | getUsageInfo ()
| Returns performance statistics for the socket. More...
bool | isConnected ()
| return connection status More...
*hash | list ()
| returns a hash with message information from the `"LIST"` command (http://tools.ietf.org/html/rfc1939#page-6) More...
| logPassword (bool pwd)
| log password More...
bool | logPassword ()
| returns the log password flag More...
| noop ()
| send a `"NOOP"` command (http://tools.ietf.org/html/rfc1939#page-9) to the POP3 server More...
| noquit (bool n_noquit)
| sets the `"noquit"` flag More...
bool | noquit ()
| return the `"noquit"` flag; if this flag is True, then no `"QUIT"` command is sent to the POP3 server when disconnecting, which can ensure that no changes are committed to the server (for example with gmail) More...
| reset ()
| send a `"RSET"` command (http://tools.ietf.org/html/rfc1939#page-9) to the POP3 server which will unmark messages marked for deletion More...
| setConnectTimeout (timeout to)
| sets the connect timeout More...
| setEventQueue (Qore::Thread::Queue queue, auto arg, *bool with_data)
| Sets a Queue object to receive socket events. More...
| setEventQueue ()
| Removes any Queue object so that socket events are no longer added to the Queue. More...
| setReadTimeout (timeout to)
| sets the read timeout More...
nothing | setWarningQueue (int warning_ms, int warning_bs, Queue queue, auto arg, timeout min_ms=1s)
| Sets a Queue object to receive socket warnings. More...
| starttls (bool n_starttls)
| sets the flag for using the `"STLS"` command after connecting (RFC 2595); this is only used if the TLS/SSL flag is False More...
bool | starttls ()
| returns the `"starttls"` flag (RFC 2595) More...
hash | stat ()
| returns a hash with status information from the `"STAT"` command (http://tools.ietf.org/html/rfc1939#page-6) More...
| tls (bool n_tls)
| sets the TLS/SSL flag More...
bool | tls ()
| returns the TLS/SSL flag More...

## Public Attributes

const | POP3Port = 110
| default POP3 port
const | POP3SPort = 995
| default POP3S port
const | Protocols = ...
| accepted protocols

## Detailed Description

This class provides the interface to POP3 servers and supports optional TLS/SSL encryption.

This class uses a Mutex lock in each Pop3Client object to ensure thread serialization to the underlying socket and its internal configuration, so it is safe to access in a multithreaded context.

Connection to and authentication with the POP3 server is made implicitly by calling a Pop3Client method that requires a connection; it is not necessary to call Pop3Client::connect() explicitly.

This class supports automatic recognition and use of APOP authentication (RFC-1939 p15) if an RFC822-compliant msg-id is included in the last part of the login string sent by the POP3 server when connecting.

Encrypted connections to POP3 servers are also supported in the following ways:

- to connect immediately with a TLS/SSL connection, use the `"pop3s"` protocol (URI scheme) in the URL, or set the TLS/SSL flag manually by calling Pop3Client::tls(bool).
- to connect with an unencrypted connection and then upgrade to an encrypted connection using the `"STLS"` command, set the `"starttls"` flag by calling Pop3Client::starttls(bool)

This class will not mark messages for deletion automatically; to mark messages for deletion, call the Pop3Client::del() method with the message ID to delete or a list of message IDs. Note that some POP3 servers (for example gmail), will mark the messages as read anyway and make them unavailable on the next request after disconnecting even if the messages were not marked for deletion manually. To avoid this, set the `"noquit"` flag by calling Pop3Client::noquit(bool). This will suppress the `"QUIT"` message when disconnecting which should keep any compiant POP3 server from committing any changes related to the current POP3 session.

## Member Function Documentation

## clearStats()

Pop3Client::Pop3Client::clearStats | ( |  | ) |

Clears performance statistics.

Example:
  pop3.clearStats();

Since
  Pop3Client 1.3

See also
  getUsageInfo()

## clearWarningQueue()

nothing Pop3Client::Pop3Client::clearWarningQueue | ( |  | ) |

Removes any warning Queue object from the Socket.

Example:
  pop3.clearWarningQueue();

See also
  setWarningQueue()

Since
  Pop3Client 1.3

## connect()

Pop3Client::Pop3Client::connect | ( |  | ) |

Connect to the server with the connection parameters set in the constructor()

Example:
  pop3.connect();

Note
  - It is not necessary to call this method explicitly; connections are made implicitly by calling a method that requires a connection
  - For possible exceptions, see Qore's Socket::connect() method
  - This method communicates with the POP3 server with the internal Socket object and therefore is subject to thread serialization

Exceptions

  POP3-SERVER-ERROR | the POP3 server responded with an error message

## constructor()

Pop3Client::Pop3Client::constructor | ( | string | url,
|  | *code | log,
|  | *code | dbglog
| ) |  |

creates the Pop3Client object

Parameters

  url

  the URL of the POP3 server including at least the username, password, and a target host or port on the local system (enclose the address or hostname in square brackets like `"[ipv6.host.com]"` to connect using the IPv6 protocol or use square brackets to delineate an IPv6 address from the port number as in ex: `"[fe80::21c:42ff:fe00:8]:110"`); accepted protocols (URI schemes) are as follows:
  - `"pop3"`: non-encrypted POP3 connections
  - `"pop3s"`: encrypted POP3 connections
  If no protocol (URI scheme) is given in the URL (ex: `"pop.gmail.com"`) then `"pop3"` is assumed; if no port is given, then either POP3Port (for `"pop3"`) or POP3SPort (for `"pop3s"`) is as the default port number depending on the protocol.

  log | an optional closure or call reference for log messages; a single string argument will be passed to this code for logging
  dbglog | an optional closure or call reference for debugging/technical log messages; a single string argument will be passed to this code for logging

Example:
  Pop3Client pop3("pop3s://user@gmail.com:password@pop.gmail.com");

Exceptions

  PARSE-URL-ERROR | the URL given could not be parsed
  POP3-URL-ERROR | the protocol given was unknown, no target, username or password in URL

## del() [1/2]

Pop3Client::Pop3Client::del | ( | softstring | msg | ) |

sends a `"DELE"` command (http://tools.ietf.org/html/rfc1939#page-8) to the POP3 server to mark the given message as deleted

Parameters

  msg | the message number to delete

Example:
  pop3.del(msgid);

Exceptions

  POP3-SERVER-ERROR | the POP3 server responded with an error message

Note
  This method communicates with the POP3 server with the internal Socket object and therefore is subject to thread serialization

## del() [2/2]

Pop3Client::Pop3Client::del | ( | list | l | ) |

sends a `"DELE"` command (http://tools.ietf.org/html/rfc1939#page-8) to the POP3 server to mark the given message as deleted

Parameters

  l | the list of message numbers to delete

Example:
  pop3.del(msgidlist);

Note
  This method communicates with the POP3 server with the internal Socket object and therefore is subject to thread serialization

## destructor()

Pop3Client::Pop3Client::destructor | ( |  | ) |

disconnects if connected and destroys the object

if any exceptions occur during the disconnection, they are sent to the debug log closure/call reference

## disconnect()

Pop3Client::Pop3Client::disconnect | ( |  | ) |

disconnect from the server

Example:
  pop3.disconnect();

## forceDisconnect()

Pop3Client::Pop3Client::forceDisconnect | ( |  | ) |

force disconnect of socket without error

Example:
  pop3.forceDisconnect();

Note
  This method communicates with the POP3 server with the internal Socket object and therefore is subject to thread serialization

## getConnectTimeoutDate()

date Pop3Client::Pop3Client::getConnectTimeoutDate | ( |  | ) |

returns the connect timeout as a relative time value

Example:
  date timeout = pop3.getConnectTimeoutDate();

## getConnectTimeoutMs()

int Pop3Client::Pop3Client::getConnectTimeoutMs | ( |  | ) |

returns the connect timeout as an integer giving milliseconds

Example:
  int ms = pop3.getConnectTimeoutMs();

## getMail()

*hash Pop3Client::Pop3Client::getMail | ( |  | ) |

returns a hash of mail messages keyed by message ID or NOTHING if no messages are available on the server

Returns
  a hash of mail messages keyed by message ID or NOTHING if no messages are available on the server; the value of each hash key will have the following keys:
  - `size:` the original raw message size in bytes
  - `msg:` a MailMessage::Message object representing the message and any attachments

Example:
  *hash mh = pop3.getMail();

Exceptions

  POP3-SERVER-ERROR | the POP3 server responded with an error message

## getReadTimeoutDate()

date Pop3Client::Pop3Client::getReadTimeoutDate | ( |  | ) |

returns the read timeout as a relative time value

Example:
  date timeout = pop3.getReadTimeoutDate();

## getReadTimeoutMs()

int Pop3Client::Pop3Client::getReadTimeoutMs | ( |  | ) |

returns the read timeout as an integer giving milliseconds

Example:
  int ms = pop3.getReadTimeoutMs();

## getTarget()

string Pop3Client::Pop3Client::getTarget | ( |  | ) |

Returns the connection target string.

Since
  Pop3Client 1.6

## getUsageInfo()

hash<auto> Pop3Client::Pop3Client::getUsageInfo | ( |  | ) |

Returns performance statistics for the socket.

Example:
  hash<auto> h = pop3.getUsageInfo();

Returns
  a hash with the following keys:
  - `"bytes_sent"`: an integer giving the total amount of bytes sent
  - `"bytes_recv"`: an integer giving the total amount of bytes received
  - `"us_sent"`: an integer giving the total number of microseconds spent sending data
  - `"us_recv"`: an integer giving the total number of microseconds spent receiving data
  - `"arg"`: (only if warning values have been set with Pop3Client::setWarningQueue()) the optional argument for warning hashes
  - `"timeout"`: (only if warning values have been set with Pop3Client::setWarningQueue()) the warning timeout in microseconds
  - `"min_throughput"`: (only if warning values have been set with Pop3Client::setWarningQueue()) the minimum warning throughput in bytes/sec

Since
  Pop3Client 1.3

See also
  clearStats()

## isConnected()

bool Pop3Client::Pop3Client::isConnected | ( |  | ) |

return connection status

Example:
  bool b = pop3.isConnected();
  printf("connected to the POP3 server: %y\n", b);

## list()

*hash Pop3Client::Pop3Client::list | ( |  | ) |

returns a hash with message information from the `"LIST"` command (http://tools.ietf.org/html/rfc1939#page-6)

if the object is not already connected, then a connection is made and authenticated to place the connection in the `"TRANSACTION"` state before executing the POP3 command

Returns
  NOTHING if no messages are available, or a hash with message information from the `"LIST"` command, where each hash key is a unique message ID, and the value of each key is a hash with a single key: `"size"`, giving the size of the message in bytes

Example:
  *hash h = pop3.list();
  HashIterator hi(h);
  map printf("%s: %d byte%s\n", $1.getKey(), $1.getValue(), $1.getValue() == 1 ? "" : "s"), hi;

Exceptions

  POP3-SERVER-ERROR | the POP3 server responded with an error message

Note
  This method communicates with the POP3 server with the internal Socket object and therefore is subject to thread serialization

## logPassword() [1/2]

Pop3Client::Pop3Client::logPassword | ( | bool | pwd | ) |

log password

Parameters

  pwd | if True then log the password in the debug log (if any is set)

Example:
  pop3.logPassword(True);

## logPassword() [2/2]

bool Pop3Client::Pop3Client::logPassword | ( |  | ) |

returns the log password flag

Example:
  bool b = pop3.logPassword();

## noop()

Pop3Client::Pop3Client::noop | ( |  | ) |

send a `"NOOP"` command (http://tools.ietf.org/html/rfc1939#page-9) to the POP3 server

Example:
  pop3.noop();

Exceptions

  POP3-SERVER-ERROR | the POP3 server responded with an error message

Note
  This method communicates with the POP3 server with the internal Socket object and therefore is subject to thread serialization

## noquit() [1/2]

Pop3Client::Pop3Client::noquit | ( | bool | n_noquit | ) |

sets the `"noquit"` flag

Parameters

  n_noquit | if True then no `"QUIT"` command is sent when disconnecting from the POP3 server; this can ensure that no changes are committed to the server (for example with gmail)

Example:
  pop3.noquit(True);

## noquit() [2/2]

bool Pop3Client::Pop3Client::noquit | ( |  | ) |

return the `"noquit"` flag; if this flag is True, then no `"QUIT"` command is sent to the POP3 server when disconnecting, which can ensure that no changes are committed to the server (for example with gmail)

The `"noquit"` flag is always False unless explicitly set to True

Returns
  the `"noquit"` flag; if this flag is True, then no `"QUIT"` command is sent to the POP3 server when disconnecting, which can ensure that no changes are committed to the server (for example with gmail)

Example:
  bool b = pop3.noquit();

## reset()

Pop3Client::Pop3Client::reset | ( |  | ) |

send a `"RSET"` command (http://tools.ietf.org/html/rfc1939#page-9) to the POP3 server which will unmark messages marked for deletion

Example:
  pop3.reset();

Exceptions

  POP3-SERVER-ERROR | the POP3 server responded with an error message

Note
  This method communicates with the POP3 server with the internal Socket object and therefore is subject to thread serialization

## setConnectTimeout()

Pop3Client::Pop3Client::setConnectTimeout | ( | timeout | to | ) |

sets the connect timeout

Example:
  pop3.setConnectTimeout(10s);

## setEventQueue() [1/2]

Pop3Client::Pop3Client::setEventQueue | ( | Qore::Thread::Queue | queue,
|  | auto | arg,
|  | *bool | with_data
| ) |  |

Sets a Queue object to receive socket events.

Example:
  pop3.setEventQueue(queue);

Parameters

  queue | the Queue object to receive socket events; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown
  arg | an argument that will be included in each event hash in the arg key
  with_data | if True, then the actual raw data transferred / received is also included in the events

Exceptions

  QUEUE-ERROR | the Queue passed has a maximum size set

See also
  I/O Event Handling for more information

Since
  Pop3Client 1.8

## setEventQueue() [2/2]

Pop3Client::Pop3Client::setEventQueue | ( |  | ) |

Removes any Queue object so that socket events are no longer added to the Queue.

Example:
  pop3.setEventQueue();

See also
  I/O Event Handling for more information

Since
  Pop3Client 1.8

## setReadTimeout()

Pop3Client::Pop3Client::setReadTimeout | ( | timeout | to | ) |

sets the read timeout

Example:
  pop3.setReadTimeout(20s);

## setWarningQueue()

nothing Pop3Client::Pop3Client::setWarningQueue | ( | int | warning_ms,
|  | int | warning_bs,
|  | Queue | queue,
|  | auto | arg,
|  | timeout | min_ms = `1s`
| ) |  |

Sets a Queue object to receive socket warnings.

Example:
  pop3.setWarningQueue(5000, 5000, queue, "socket-1");

Parameters

  warning_ms

  the threshold in milliseconds for individual socket actions (send, receive, connect), if exceeded, a socket warning is placed on the warning queue with the following keys:
  - `"type"`: a string with the constant value `"SOCKET-OPERATION-WARNING"`
  - `"operation"`: a string giving the operation that caused the warning (ex: `"connect"`)
  - `"us"`: an integer giving the number of microseconds for the operation
  - `"timeout"`: an integer giving the warning threshold in microseconds
  - `"arg"`: if any `"arg"` argument is passed to the Pop3Client::setWarningQueue() method, it will be included in the warning hash here

  warning_bs

  value in bytes per second; if any call has performance below this threshold, a socket warning is placed on the warning queue with the following keys:
  - `"type"`: a string with the constant value `"SOCKET-THROUGHPUT-WARNING"`
  - `"dir"`: either `"send"` or `"recv"` depending on the direction of the data flow
  - `"bytes"`: the amount of bytes sent
  - `"us"`: an integer giving the number of microseconds for the operation
  - `"bytes_sec"`: a float giving the transfer speed in bytes per second
  - `"threshold"`: an integer giving the warning threshold in bytes per second
  - `"arg"`: if any `"arg"` argument is passed to the Pop3Client::setWarningQueue() method, it will be included in the warning hash here

  queue | the Queue object to receive warning events
  arg | an optional argument to be placed in the `"arg"` key in each warning hash (could be used to identify the socket for example)
  min_ms | the minimum transfer time with a resolution of milliseconds for a transfer to be eligible for triggering a warning; transfers that take less than this period of time are not eligible for raising a warning

Exceptions

  QUEUE-ERROR | the Queue passed has a maximum size set
  SOCKET-SETWARNINGQUEUE-ERROR | at least one of warning_ms and warning_bs must be > 0

See also
  clearWarningQueue()

Since
  Pop3Client 1.3

## starttls() [1/2]

Pop3Client::Pop3Client::starttls | ( | bool | n_starttls | ) |

sets the flag for using the `"STLS"` command after connecting (RFC 2595); this is only used if the TLS/SSL flag is False

Parameters

  n_starttls | if True then issue the `"STLS"` command after making an unencrypted connection; if this flag is set then the client will negotiate a TLS/SSL connection with the server after making an unencrypted connection

Example:
  pop3.starttls(True);

## starttls() [2/2]

bool Pop3Client::Pop3Client::starttls | ( |  | ) |

returns the `"starttls"` flag (RFC 2595)

Example:
  bool b = pop3.starttls();

## stat()

hash Pop3Client::Pop3Client::stat | ( |  | ) |

returns a hash with status information from the `"STAT"` command (http://tools.ietf.org/html/rfc1939#page-6)

if the object is not already connected, then a connection is made and authenticated to place the connection in the `"TRANSACTION"` state before executing the POP3 command

Returns
  a hash with status information from the `"STAT"` command with the following keys:
  - `num:` the number of messages available
  - `size:` the size of data available in bytes

Example:
  hash h = pop3.stat();

Exceptions

  POP3-SERVER-ERROR | the POP3 server responded with an error message

Note
  This method communicates with the POP3 server with the internal Socket object and therefore is subject to thread serialization

## tls() [1/2]

Pop3Client::Pop3Client::tls | ( | bool | n_tls | ) |

sets the TLS/SSL flag

Parameters

  n_tls | if True then use TLS/SSL; if the TLS/SSL flag is set then the client will negotiate a TLS/SSL connection with the server after connecting

Example:
  pop3.tls(True);

## tls() [2/2]

bool Pop3Client::Pop3Client::tls | ( |  | ) |

returns the TLS/SSL flag

Example:
  bool b = pop3.tls();