|
Qore SmtpClient Module Reference
1.6
|
the class that's used to communicate with an SMTP server and supports optional TLS/SSL encryption More...
Public Member Functions | |
| 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 | |
| date | getReadTimeoutDate () |
| returns the read timeout as a relative time value | |
| int | getReadTimeoutMs () |
| returns the read timeout as an integer giving milliseconds | |
| hash | getUsageInfo () |
| Returns performance statistics for the socket. More... | |
| bool | isConnected () |
| return connection status | |
| hash | sendMessage (MailMessage::Message message) |
| send a Message to the server More... | |
| setConnectTimeout (timeout to) | |
| sets the connect timeout | |
| 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... | |
| ssl (bool n_ssl) | |
| sets the SSL connection flag More... | |
| bool | ssl () |
| returns the SSL connection flag | |
| test (bool ns) | |
| sets or disables test mode; no connections are made in test mode | |
| bool | test () |
| returns the test mode flag | |
| tls (bool n_tls) | |
| sets the TLS/SSL flag More... | |
| bool | tls () |
| returns the TLS/SSL flag | |
Public Attributes | |
| const | EsmtpPort = 587 |
| default ESMTP port | |
| const | Protocols |
| procotol config | |
| const | SmtpPort = 25 |
| default SMTP port | |
| const | 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 | |
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.
| SmtpClient::SmtpClient::clearStats | ( | ) |
| nothing SmtpClient::SmtpClient::clearWarningQueue | ( | ) |
Removes any warning Queue object from the Socket.
| SmtpClient::SmtpClient::connect | ( | ) |
Connect to the server with the connection parameters set in the constructor()
| SmtpClient::SmtpClient::constructor | ( | string | host, |
| softint | port, | ||
| *code | log, | ||
| *code | dbglog | ||
| ) |
creates the SmtpClient object
| host | the hostname of the SMTP server (use "[hostname]" to explicitly specify an ipv6 connection) |
| port | the port number of the SMTP server |
| log | a closure or call reference for log messages; a single string argument will be passed to this code for logging |
| dbglog | a closure for debugging/technical log messages; a single string argument will be passed to this code for logging |
| SmtpClient::SmtpClient::constructor | ( | string | url, |
| *code | log, | ||
| *code | dbglog | ||
| ) |
creates the SmtpClient object
| url | the 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 |
| 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 |
| PARSE-URL-ERROR | the url argument could not be parsed with parse_url() |
| SMTPCLIENT-UNKNOWN-PROTOCOL | the protocol (scheme) given is unknown or unsupported |
| SMTPCLIENT-INVALID-AUTHENTICATION | partial authentication credentials passed; the username or password is missing |
| 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
| SmtpClient::SmtpClient::disconnect | ( | ) |
disconnect from the server
| SmtpClient::SmtpClient::forceDisconnect | ( | ) |
force disconnect of socket without error
| hash SmtpClient::SmtpClient::getUsageInfo | ( | ) |
Returns performance statistics for the socket.
"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| hash SmtpClient::SmtpClient::sendMessage | ( | MailMessage::Message | message | ) |
send a Message to the server
| message | the Message to send |
"code": the return code, "desc": the string description):HELO or EHLO: a hash of the reply received from the HELO or EHLO commandRCPT: hash keyed by email address with hash return structures values for the RCPT TO commandMSGID: return structure after the send; generally contains message idQUIT: the server response of the disconnect command| MESSAGE-ERROR | the message is incomplete and cannot be sent |
sets the username and password for authenticated connections
| n_user | the username to set for authentication |
| n_pass | the password to set for authentication |
| 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.
| 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:
|
| 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:
|
| 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 |
| 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 |
| SmtpClient::SmtpClient::ssl | ( | bool | n_ssl | ) |
sets the SSL connection flag
| n_ssl | if 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 |
| SmtpClient::SmtpClient::tls | ( | bool | n_tls | ) |
sets the TLS/SSL flag
| n_tls | if 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 |