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

#include <Pop3Client.qm.dox.h>

Public Member Methods
	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 (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...

	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...

	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...

bool	logPassword ()
	returns the log password flag More...

	logPassword (bool pwd)
	log password More...

	noop ()
	send a `"NOOP"` command (http://tools.ietf.org/html/rfc1939#page-9) to the POP3 server 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...

	noquit (bool n_noquit)
	sets the `"noquit"` flag 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 ()
	Removes any Queue object so that socket events are no longer added to the Queue. More...

	setEventQueue (Qore::Thread::Queue queue, auto arg, *bool with_data)
	Sets a Queue object to receive socket events. 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...

bool	starttls ()
	returns the `"starttls"` flag (RFC 2595) 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...

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

bool	tls ()
	returns the TLS/SSL flag More...

	tls (bool n_tls)
	sets 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://[email protected]:[email protected]");

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 ( 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

◆ del() [2/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

◆ 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]

bool Pop3Client::Pop3Client::logPassword ( )

returns the log password flag

Example:: bool b = pop3.logPassword();

◆ logPassword() [2/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);

◆ 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]

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();

◆ noquit() [2/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);

◆ 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 ( )

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

◆ setEventQueue() [2/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

◆ 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]

bool Pop3Client::Pop3Client::starttls ( )

returns the "starttls" flag (RFC 2595)

Example:: bool b = pop3.starttls();

◆ starttls() [2/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);

◆ 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]

bool Pop3Client::Pop3Client::tls ( )

returns the TLS/SSL flag

Example:: bool b = pop3.tls();

◆ tls() [2/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);

Public Member Methods

Public Attributes

Detailed Description

Member Function Documentation

◆ clearStats()

◆ clearWarningQueue()

◆ connect()

◆ constructor()

◆ del() [1/2]

◆ del() [2/2]

◆ destructor()

◆ disconnect()

◆ forceDisconnect()

◆ getConnectTimeoutDate()

◆ getConnectTimeoutMs()

◆ getMail()

◆ getReadTimeoutDate()

◆ getReadTimeoutMs()

◆ getTarget()

◆ getUsageInfo()

◆ isConnected()

◆ list()

◆ logPassword() [1/2]

◆ logPassword() [2/2]

◆ noop()

◆ noquit() [1/2]

◆ noquit() [2/2]

◆ reset()

◆ setConnectTimeout()

◆ setEventQueue() [1/2]

◆ setEventQueue() [2/2]

◆ setReadTimeout()

◆ setWarningQueue()

◆ starttls() [1/2]

◆ starttls() [2/2]

◆ stat()

◆ tls() [1/2]

◆ tls() [2/2]