This class provides the interface to POP3 servers. More...

#include <Pop3Client.qm.dox.h>

Inheritance diagram for Pop3Client::Pop3Client:

Public Member Methods
	clearStats ()
	Clears performance statistics.

nothing	clearWarningQueue ()
	Removes any warning Queue object from the Socket.

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

	constructor (string url, *hash< auto > opts)
	Creates the Pop3Client object.

	del (list< auto > l)
	Sends a `"DELE"` command to delete one or more messages on the server.

	del (softstring msg)
	Sends a `"DELE"` command to delete a single message on the server.

	destructor ()
	disconnects if connected and destroys the object

	disconnect ()
	disconnect from the server

	forceDisconnect ()
	force disconnect of socket without error

date	getConnectTimeoutDate ()
	returns the connect timeout as a relative time value

int	getConnectTimeoutMs ()
	returns the connect timeout as an integer giving milliseconds

date	getIoTimeoutDate ()
	returns the i/o timeout as a relative time value

int	getIoTimeoutMs ()
	returns the i/o timeout as an integer giving milliseconds

*hash< auto >	getMail ()
	returns a hash of mail messages keyed by message ID or NOTHING if no messages are available on the server

MailMessage::Message	getMessage (string id)
	Retrieves a particular mail message by its ID.

string	getTarget ()
	Returns the connection target string.

hash< auto >	getUsageInfo ()
	Returns performance statistics for the socket.

bool	isConnected ()
	return connection status

*hash< auto >	list ()
	Returns a hash with message information from the `"LIST"` command.

bool	logPassword ()
	returns the log password flag

	logPassword (bool pwd)
	log password

	noop ()
	send a `"NOOP"` command to the POP3 server

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)

	noquit (bool noquit)
	Sets the `"noquit"` flag.

	reset ()
	Send a `"RSET"` command to the POP3 server which will unmark messages marked for deletion.

	setConnectTimeout (timeout to)
	sets the connect timeout

	setEventQueue ()
	Removes any Queue object, prohibiting the collection of socket events.

	setEventQueue (Qore::Thread::Queue queue, auto arg, *bool with_data)
	Sets a Queue object to receive socket events.

	setIoTimeout (timeout to)
	sets the I/o timeout

nothing	setWarningQueue (int warning_ms, int warning_bs, Queue queue, auto arg, timeout min_ms=1s)
	Sets a Queue object to receive socket warnings.

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

	starttls (bool starttls)
	sets the flag for using the `"STLS"` command after connecting

hash< auto >	stat ()
	Returns a hash with status information from the `"STAT"` command.

bool	tls ()
	returns the TLS/SSL flag

	tls (bool tls)
	sets the TLS/SSL flag

Public Attributes
const	CtrlA = chr(1)
	For SASL XOAUTH2 logins.

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.

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,
		*hash< auto >	opts
	)

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.

opts

options for the object; supported options:

connect_timeout (int): the connect timeout in milliseconds
io_timeout (int): the I/O timeout in milliseconds
logger (LoggerInterface): a logger to use for logging
password (string): the password for the connection
read_timeout (int): the read timeout in milliseconds
tls (bool): execute the STLS command after connecting with insecure connections
token (string): if set, then SASL XOAUTH2 will be used to send access tokens to the server for login
username (string): the username for the connection

Example:: # this will use SASL XOAUTH2 to perform the login

Pop3Client pop3("pop3s://pop.gmail.com", {

"username": "user@gmail.com",

"token": "xxx",

});

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< auto > l )

Sends a "DELE" command to delete one or more messages on the server.

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

See also: http://tools.ietf.org/html/rfc1939#page-8 for more information about this command

◆ del() [2/2]

Pop3Client::Pop3Client::del ( softstring msg )

Sends a "DELE" command to delete a single message on the server.

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

See also: http://tools.ietf.org/html/rfc1939#page-8 for more information about this command

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

◆ getIoTimeoutDate()

date Pop3Client::Pop3Client::getIoTimeoutDate ( )

returns the i/o timeout as a relative time value

Example:: date timeout = pop3.getIoTimeoutDate();

◆ getIoTimeoutMs()

int Pop3Client::Pop3Client::getIoTimeoutMs ( )

returns the i/o timeout as an integer giving milliseconds

Example:: int ms = pop3.getIoTimeoutMs();

◆ getMail()

*hash< auto > 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<auto> mh = pop3.getMail();

Exceptions

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

◆ getMessage()

MailMessage::Message Pop3Client::Pop3Client::getMessage ( string id )

Retrieves a particular mail message by its ID.

Parameters

id	The message ID to retrieve

Returns: the mail message object corresponding to the argument

Exceptions

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

◆ 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< auto > Pop3Client::Pop3Client::list ( )

Returns a hash with message information from the "LIST" command.

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

See also: http://tools.ietf.org/html/rfc1939#page-6 for more information about this command

◆ 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 the password is logged with a `DEBUG` level if any logger is set

Example:: pop3.logPassword(True);

◆ noop()

Pop3Client::Pop3Client::noop ( )

send a "NOOP" command 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

See also: http://tools.ietf.org/html/rfc1939#page-9 for more information about this command

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

Sets the "noquit" flag.

Parameters

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

See also: http://tools.ietf.org/html/rfc1939#page-9 for more information about this command

◆ setConnectTimeout()

Pop3Client::Pop3Client::setConnectTimeout ( timeout to )

sets the connect timeout

Example:: pop3.setConnectTimeout(10s);

◆ setEventQueue() [1/2]

Pop3Client::Pop3Client::setEventQueue ( )

Removes any Queue object, prohibiting the collection of socket events.

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

◆ setIoTimeout()

Pop3Client::Pop3Client::setIoTimeout ( timeout to )

sets the I/o timeout

Example:: pop3.setIoTimeout(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 starttls )

sets the flag for using the "STLS" command after connecting

Parameters

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

Note: The STLS command is only executed with insecure connections

See also: RFC 2595 for more information about the STLS command

◆ stat()

hash< auto > Pop3Client::Pop3Client::stat ( )

Returns a hash with status information from the "STAT" command.

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

See also: http://tools.ietf.org/html/rfc1939#page-6 for more information about this command

◆ tls() [1/2]

bool Pop3Client::Pop3Client::tls ( )

returns the TLS/SSL flag

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

◆ tls() [2/2]

Pop3Client::Pop3Client::tls ( bool tls )

sets the TLS/SSL flag

Parameters

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

◆ getIoTimeoutDate()

◆ getIoTimeoutMs()

◆ getMail()

◆ getMessage()

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

◆ setIoTimeout()

◆ setWarningQueue()

◆ starttls() [1/2]

◆ starttls() [2/2]

◆ stat()

◆ tls() [1/2]

◆ tls() [2/2]