Qore Pop3Client Module Reference  1.9
Pop3Client::Pop3Client Class Reference

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

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-ERRORthe POP3 server responded with an error message

◆ constructor()

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

creates the Pop3Client object

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

Parameters
logan optional closure or call reference for log messages; a single string argument will be passed to this code for logging
dbglogan 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-ERRORthe URL given could not be parsed
POP3-URL-ERRORthe 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
lthe 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
msgthe message number to delete
Example:
pop3.del(msgid);
Exceptions
POP3-SERVER-ERRORthe 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-ERRORthe 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);
string printf(string fmt,...)

◆ 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-ERRORthe 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
pwdif 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-ERRORthe 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_noquitif 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-ERRORthe 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
queuethe Queue object to receive socket events; note that the Queue passed cannot have any maximum size set or a QUEUE-ERROR will be thrown
argan argument that will be included in each event hash in the arg key
with_dataif True, then the actual raw data transferred / received is also included in the events
Exceptions
QUEUE-ERRORthe 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_msthe 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_bsvalue 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
queuethe Queue object to receive warning events
argan optional argument to be placed in the "arg" key in each warning hash (could be used to identify the socket for example)
min_msthe 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-ERRORthe Queue passed has a maximum size set
SOCKET-SETWARNINGQUEUE-ERRORat 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_starttlsif 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-ERRORthe 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_tlsif 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);