Qore Pop3Client Module Reference  1.1
 All Classes Namespaces Functions Variables Groups Pages
Pop3Client::Pop3Client Class Reference

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

Public Member Functions

 constructor (string url, *code log, *code dbglog)
 creates the Pop3Client object
 
 destructor ()
 disconnects if connected and destroys the object
 
 logPassword (bool pwd)
 log password
 
bool logPassword ()
 returns the log password flag
 
 tls (bool tls)
 sets the TLS/SSL flag
 
bool tls ()
 returns the TLS/SSL flag
 
 starttls (bool starttls)
 sets the flag for using the "STLS" command after connecting (RFC 2595); this is only used if the TLS/SSL flag is False
 
bool starttls ()
 returns the "starttls" flag (RFC 2595)
 
 noquit (bool noquit)
 sets the "noquit" flag
 
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)
 
 connect ()
 Connect to the server with the connection parameters set in the constructor()
 
*hash getMail ()
 returns a hash of mail messages keyed by message ID or NOTHING if no messages are available on the server
 
hash stat ()
 returns a hash with status information from the "STAT" command (http://tools.ietf.org/html/rfc1939#page-6)
 
*hash list ()
 returns a hash with message information from the "LIST" command (http://tools.ietf.org/html/rfc1939#page-6)
 
 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
 
 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
 
 noop ()
 send a "NOOP" command (http://tools.ietf.org/html/rfc1939#page-9) to the POP3 server
 
 reset ()
 send a "RSET" command (http://tools.ietf.org/html/rfc1939#page-9) to the POP3 server which will unmark messages marked for deletion
 
bool isConnected ()
 return connection status
 
 disconnect ()
 disconnect from the server
 
 setReadTimeout (timeout to)
 sets the read timeout
 
int getReadTimeoutMs ()
 returns the read timeout as an integer giving milliseconds
 
date getReadTimeoutDate ()
 returns the read timeout as a relative time value
 
 setConnectTimeout (timeout to)
 sets the connect timeout
 
int getConnectTimeoutMs ()
 returns the connect timeout as an integer giving milliseconds
 
date getConnectTimeoutDate ()
 returns the connect timeout as a relative time value
 
 forceDisconnect ()
 force disconnect of socket without error
 

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 SMTP 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 SMTP server from committing any changes related to the current POP3 session.

Member Function Documentation

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 SMTP server with the internal Socket object and therefore is subject to thread serialization
Exceptions
POP3-SERVER-ERRORthe POP3 server responded with an error message
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]:1110"); 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.
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:
my Pop3Client $pop3("pop3s://user@gmail.com:password@pop.gmail.com");
Exceptions
PARSE-URL-ERRORthe URL given could not be parsed
POP3-URL-ERRORthe protocol given was unknown, no target, username or password in URL
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 SMTP server with the internal Socket object and therefore is subject to thread serialization
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 SMTP server with the internal Socket object and therefore is subject to thread serialization
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

Pop3Client::Pop3Client::disconnect ( )

disconnect from the server

Example:
$pop3.disconnect();
Pop3Client::Pop3Client::forceDisconnect ( )

force disconnect of socket without error

Example:
$pop3.forceDisconnect();
Note
This method communicates with the SMTP server with the internal Socket object and therefore is subject to thread serialization
date Pop3Client::Pop3Client::getConnectTimeoutDate ( )

returns the connect timeout as a relative time value

Example:
my date $timeout = $pop3.getConnectTimeoutDate();
int Pop3Client::Pop3Client::getConnectTimeoutMs ( )

returns the connect timeout as an integer giving milliseconds

Example:
my int $ms = $pop3.getConnectTimeoutMs();
*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:
my *hash $mh = $pop3.getMail();
Exceptions
POP3-SERVER-ERRORthe POP3 server responded with an error message
date Pop3Client::Pop3Client::getReadTimeoutDate ( )

returns the read timeout as a relative time value

Example:
my date $timeout = $pop3.getReadTimeoutDate();
int Pop3Client::Pop3Client::getReadTimeoutMs ( )

returns the read timeout as an integer giving milliseconds

Example:
my int $ms = $pop3.getReadTimeoutMs();
bool Pop3Client::Pop3Client::isConnected ( )

return connection status

Example:
my bool $b = $pop3.isConnected();
printf("connected to the POP3 server: %y\n", $b);
*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:
my *hash $h = $pop3.list();
my 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 SMTP server with the internal Socket object and therefore is subject to thread serialization
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);
bool Pop3Client::Pop3Client::logPassword ( )

returns the log password flag

Example:
my bool $b = $pop3.logPassword();
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 SMTP server with the internal Socket object and therefore is subject to thread serialization
Pop3Client::Pop3Client::noquit ( bool  noquit)

sets the "noquit" flag

Parameters
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);
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:
my bool $b = $pop3.noquit();
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 SMTP server with the internal Socket object and therefore is subject to thread serialization
Pop3Client::Pop3Client::setConnectTimeout ( timeout  to)

sets the connect timeout

Example:
$pop3.setConnectTimeout(10s);
Pop3Client::Pop3Client::setReadTimeout ( timeout  to)

sets the read timeout

Example:
$pop3.setReadTimeout(20s);
Pop3Client::Pop3Client::starttls ( bool  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
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);
bool Pop3Client::Pop3Client::starttls ( )

returns the "starttls" flag (RFC 2595)

Example:
my bool $b = $pop3.starttls();
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:
my hash $h = $pop3.stat();
Exceptions
POP3-SERVER-ERRORthe POP3 server responded with an error message
Note
This method communicates with the SMTP server with the internal Socket object and therefore is subject to thread serialization
Pop3Client::Pop3Client::tls ( bool  tls)

sets the TLS/SSL flag

Parameters
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);
bool Pop3Client::Pop3Client::tls ( )

returns the TLS/SSL flag

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