Qore SmtpClient Module Reference 2.0
Loading...
Searching...
No Matches
SmtpClient::SmtpClient Class Reference

the class that's used to communicate with an SMTP server and supports optional TLS/SSL encryption More...

#include <SmtpClient.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 host, softint port, *code log, *code dbglog)
 creates the SmtpClient object More...
 
 constructor (string url, *code log, *code dbglog)
 creates the SmtpClient object 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
 
int getConnectTimeoutMs ()
 returns the connect timeout as an integer giving milliseconds
 
hash< auto > getInfo ()
 Returns info about the connection. More...
 
date getReadTimeoutDate ()
 returns the read timeout as a relative time value
 
int getReadTimeoutMs ()
 returns the read timeout as an integer giving milliseconds
 
string getTarget ()
 Returns the connection target string. More...
 
hash< auto > getUsageInfo ()
 Returns performance statistics for the socket. More...
 
bool isConnected ()
 return connection status
 
hash< auto > sendMessage (MailMessage::Message message)
 send a Message to the server More...
 
 setConnectTimeout (timeout to)
 sets the connect timeout
 
 setDebugLogClosure (*code log)
 Set debug log closure.
 
 setEventQueue ()
 Removes any Queue object. More...
 
 setEventQueue (Qore::Thread::Queue queue, auto arg, *bool with_data)
 Sets a Queue object to receive socket events. More...
 
 setInfoLogClosure (*code log)
 Set info log closure.
 
 setReadTimeout (timeout to)
 sets the read timeout
 
 setUserPass (string n_user, string n_pass)
 sets the username and password for authenticated connections 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 ssl ()
 returns the SSL connection flag
 
 ssl (bool n_ssl)
 sets the SSL connection flag More...
 
bool test ()
 returns the test mode flag
 
 test (bool ns)
 sets or disables test mode; no connections are made in test mode
 
bool tls ()
 returns the TLS/SSL flag
 
 tls (bool n_tls)
 sets the TLS/SSL flag More...
 

Public Attributes

const EsmtpPort = 587
 default ESMTP port
 
const Protocols
 procotol config
 
const SmtpPort = 25
 default SMTP port
 
const SmtpsPort = 465
 default SMTPS port More...
 

Detailed Description

the class that's used to communicate with an SMTP server and supports optional TLS/SSL encryption

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

Member Function Documentation

◆ clearStats()

SmtpClient::SmtpClient::clearStats ( )

Clears performance statistics.

Example:
smtp.clearStats();
Since
SmtpClient 1.3
See also
getUsageInfo()

◆ clearWarningQueue()

nothing SmtpClient::SmtpClient::clearWarningQueue ( )

Removes any warning Queue object from the Socket.

Example:
smtp.clearWarningQueue();
See also
setWarningQueue()
Since
SmtpClient 1.3

◆ connect()

SmtpClient::SmtpClient::connect ( )

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

Note
  • For possible exceptions, see Qore's Socket::connect() method
  • This method is subject to thread serialization

◆ constructor() [1/2]

SmtpClient::SmtpClient::constructor ( string  host,
softint  port,
*code  log,
*code  dbglog 
)

creates the SmtpClient object

Parameters
hostthe hostname of the SMTP server (use "[hostname]" to explicitly specify an ipv6 connection)
portthe port number of the SMTP server
loga closure or call reference for log messages; a single string argument will be passed to this code for logging
dbgloga closure for debugging/technical log messages; a single string argument will be passed to this code for logging

◆ constructor() [2/2]

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

creates the SmtpClient object

Example:
SmtpClient smtp("smtptls://user@gmail.com:password@smtp.gmail.com", \log(), \log());
Parameters
urlthe URL of the SMTP server (use "[hostname]" or "[address]" for ipv6 connections); if no protocol (scheme) and no port is given for non-UNIX sockets, then SmtpPort is used as the default port number. This argument is parsed with parse_url(); see smtpclient_protocols for a description of the handling of the protocol (scheme) component of the URL including default ports per protocol (scheme). If an unknown protocol (scheme) is given then a SMTP-UNKNOWN-PROTOCOL exception is raised
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
Exceptions
PARSE-URL-ERRORthe url argument could not be parsed with parse_url()
SMTPCLIENT-UNKNOWN-PROTOCOLthe protocol (scheme) given is unknown or unsupported
SMTPCLIENT-INVALID-AUTHENTICATIONpartial authentication credentials passed; the username or password is missing

◆ destructor()

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

SmtpClient::SmtpClient::disconnect ( )

disconnect from the server

Note
This method is subject to thread serialization

◆ forceDisconnect()

SmtpClient::SmtpClient::forceDisconnect ( )

force disconnect of socket without error

Note
This method is subject to thread serialization

◆ getInfo()

hash< auto > SmtpClient::SmtpClient::getInfo ( )

Returns info about the connection.

Returns
info about the connection with the following keys:
  • target: the connection target (host:port)
  • tls: the tls flag
  • ssl: the ssl flag
  • user: any username for the connection
  • pass: any password for the connection

◆ getTarget()

string SmtpClient::SmtpClient::getTarget ( )

Returns the connection target string.

Since
SmtpClient 1.7

◆ getUsageInfo()

hash< auto > SmtpClient::SmtpClient::getUsageInfo ( )

Returns performance statistics for the socket.

Example:
hash<auto> h = smtp.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 SmtpClient::setWarningQueue()) the optional argument for warning hashes
  • "timeout": (only if warning values have been set with SmtpClient::setWarningQueue()) the warning timeout in microseconds
  • "min_throughput": (only if warning values have been set with SmtpClient::setWarningQueue()) the minimum warning throughput in bytes/sec
Since
SmtpClient 1.3
See also
clearStats()

◆ sendMessage()

hash< auto > SmtpClient::SmtpClient::sendMessage ( MailMessage::Message  message)

send a Message to the server

Parameters
messagethe Message to send
Returns
a hash of data returned by the SMTP server (the return structure hashes described below are made up of the following keys: "code": the return code, "desc": the string description):
  • HELO or EHLO: a hash of the reply received from the HELO or EHLO command
  • RCPT: hash keyed by email address with hash return structures values for the RCPT TO command
  • MSGID: return structure after the send; generally contains message id
  • QUIT: the server response of the disconnect command
Note
This method is subject to thread serialization
Exceptions
MESSAGE-ERRORthe message is incomplete and cannot be sent

◆ setEventQueue() [1/2]

SmtpClient::SmtpClient::setEventQueue ( )

Removes any Queue object.

After this call, socket events are no longer added to any currently-set Queue

Example:
smtp.setEventQueue();
See also
I/O Event Handling for more information
Since
SmtpClient 1.8

◆ setEventQueue() [2/2]

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

Sets a Queue object to receive socket events.

Example:
smtp.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
SmtpClient 1.8

◆ setUserPass()

SmtpClient::SmtpClient::setUserPass ( string  n_user,
string  n_pass 
)

sets the username and password for authenticated connections

Parameters
n_userthe username to set for authentication
n_passthe password to set for authentication
Note
  • Currently this class only knows how to do AUTH PLAIN authentication
  • This method is subject to thread serialization

◆ setWarningQueue()

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

Sets a Queue object to receive socket warnings.

Example:
smtp.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 SmtpClient::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 SmtpClient::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
SmtpClient 1.3

◆ ssl()

SmtpClient::SmtpClient::ssl ( bool  n_ssl)

sets the SSL connection flag

Parameters
n_sslif True then connections to the SMTP server will immediately try to negotiate transport layer TSL/SSL security; will also in this case turn off the TLS/SSL "STARTTLS" application layer security flag

◆ tls()

SmtpClient::SmtpClient::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 issue a "STARTTLS" command after connecting and negotiate a secure TLS/SSL connection to the server; will also in this case turn off the SSL connection flag

Member Data Documentation

◆ SmtpsPort

const SmtpClient::SmtpClient::SmtpsPort = 465

default SMTPS port

note that this port is currently assigned to source-specific multicast audio/video (http://www.iana.org/assignments/port-numbers); it's use as a port for secure SMTP listeners (where security is enforced at the transport layer because the server immediately negotiates a TLS/SSL connection before the application protocol communication starts) is deprecated