From af79dfa2d055053c1027e20cf08f0549dc2e9ada Mon Sep 17 00:00:00 2001 From: Pawel Salek Date: Thu, 4 Mar 2010 22:21:56 +0100 Subject: Initial Commit --- doc/api.xml | 2360 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2360 insertions(+) create mode 100644 doc/api.xml (limited to 'doc/api.xml') diff --git a/doc/api.xml b/doc/api.xml new file mode 100644 index 0000000..7a49ee2 --- /dev/null +++ b/doc/api.xml @@ -0,0 +1,2360 @@ + + +
+ + + + + Brian Stafford + +
+ brian@stafford.uklinux.org +
+ + + + + + 2001,2002 + Brian Stafford + + + + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation +License, Version 1.1 or any later version published by the +Free Software Foundation with no Invariant Sections, no Front-Cover +Texts, and no Back-Cover Texts. You may obtain a copy of the +GNU Free Documentation License from the Free +Software Foundation by visiting their Web site or by writing to: Free +Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +02111-1307, USA. + + + + libESMTP API Reference + + + +This document describes the libESMTP programming interface. The libESMTP +API is intended for use as an ESMTP client within a Mail User Agent +(MUA) or other program that wishes to submit mail to a preconfigured +Message Submission Agent (MSA). + + + + + + + + Important + +libESMTP is currently under development. Consequently certain parts +of the API are subject to change between releases of the library and +certain APIs and SMTP extensions have not yet been fully implemented. + + + +Furthermore, the descriptions in this document do not necessarily reflect +currently implemented functionality. For now, regard this document more +as a statement of intent than an accurate description, or to quote +The Hitch Hikers' Guide to the Galaxy, +Much of it is apocryphal or, at the very least, wildly +inaccurate. However, where it is inaccurate, it is +definitively inaccurate. + + + +If in doubt, consult the source. The API and documentation will stabilise +as version 1.0 approaches. + + + + + + + + + + Introduction + +For the most part, the libESMTP API is a relatively thin layer over SMTP +protocol operations, that is, most API functions and their arguments are +similar to the corresponding protocol commands. Further API functions +manage a callback mechanism which is used to read messages from the +application and to report protocol progress to the application. The +remainder of the API is devoted to reporting on a completed SMTP session. + + + +Although the API closely models the protocol itself, libESMTP relieves the +programmer of all the work needed to properly implement RFC 2821 (formerly +RFC 821) and avoids many of the pitfalls in typical SMTP implementations. +It constructs SMTP commands, parses responses, provides socket buffering +and pipelining, where appropriate provides for TLS connections and +provides a failover mechanism based on DNS allowing multiple redundant +MSAs. Furthermore, support for the SMTP extension mechanism is +incorporated by design rather than as an afterthought. + + + +There is limited support for processing RFC 2822 message headers. This +is intended to ensure that messages copied to the SMTP server have their +correct complement of headers. Headers that should not be present are +stripped and reasonable defaults are provided for missing headers. In +addition, the header API allows the defaults to be tuned and provides a +mechanism to specify message headers when this might be difficult to do +directly in the message data. + + + +libESMTP does not implement MIME [RFC 2045] since MIME is orthogonal +to RFC 2822. It is expected that a separate library will be used to +construct MIME documents. libESMTP ensures that top level MIME headers +are passed unaltered and the header API functions are guaranteed to fail +if any header in the name space reserved for MIME is specified, thus +ensuring that MIME documents are not accidentally corrupted. + + + + + SMTP Extensions + + +libESMTP supports the following SMTP extensions. Those extensions which +are useful only in Message Transport Agents (MTA) will not be implemented +in libESMTP. + + + + [RFC 1893] ENHANCEDSTATUSCODES + [RFC 2920] PIPELINING + [RFC 1891] DSN + [RFC 2554] AUTH (SASL) + [RFC 2487] STARTTLS + [RFC 1870] SIZE + [RFC 1985] ETRN + [RFC 1652] 8BITMIME + [RFC 2852] DELIVERBY + + + +Supports is planned for the following SMTP extensions. As new SMTP +extensions are defined, they will be implemented if they are relevant +for use in programs that submit mail. + + + + [RFC 3030] CHUNKING + [RFC 3030] BINARYMIME + + + +Please note that certain of the SMTP extensions are processed internally +to libESMTP and do not require corresponding API functions. + + + + + API + + +The libESMTP API is intended to be a relatively small and lightweight +interface to the SMTP protocol and its extensions. However, given the +number of API functions in libESMTP, this assertion is questionable. In +mitigation, many of these are necessary because the internal structures +are opaque to the application and most of them are used to define the +messages and recipients to be transferred to the SMTP server during the +protocol session. Similarly a significant number of functions are used +to query the status of the transfer after the event. The entire SMTP +protocol session is performed by only one function call. + + + + Functions + +smtp_message_t smtp_add_message (smtp_session_t session); +smtp_recipient_t smtp_add_recipient (smtp_message_t message, const char *mailbox); +int smtp_auth_set_context (smtp_session_t session, auth_context_t context); +smtp_session_t smtp_create_session (void); +int smtp_destroy_session (smtp_session_t session); +int smtp_dsn_set_envid (smtp_message_t message, const char *envid); +int smtp_dsn_set_notify (smtp_recipient_t recipient, enum notify_flags flags); +int smtp_dsn_set_orcpt (smtp_recipient_t recipient, const char *address_type, const char *address); +int smtp_dsn_set_ret (smtp_message_t message, enum ret_flags flags); +int smtp_enumerate_messages (smtp_session_t session, smtp_enumerate_messagecb_t cb, void *arg); +int smtp_enumerate_recipients (smtp_message_t message, smtp_enumerate_recipientcb_t cb, void *arg); +int smtp_errno (void); +smtp_etrn_node_t smtp_etrn_add_node (smtp_session_t session, int option, const char *node); +int smtp_etrn_enumerate_nodes (smtp_session_t session, smtp_etrn_enumerate_nodecb_t cb, void *arg); +void *smtp_etrn_get_application_data (smtp_etrn_node_t node); +const smtp_status_t *smtp_etrn_node_status (smtp_etrn_node_t node); +void *smtp_etrn_set_application_data (smtp_etrn_node_t node, void *data); +void *smtp_get_application_data (smtp_session_t session); +void *smtp_message_get_application_data (smtp_message_t message); +int smtp_message_reset_status (smtp_message_t recipient); +void *smtp_message_set_application_data (smtp_message_t message, void *data); +const smtp_status_t *smtp_message_transfer_status (smtp_message_t message); +int smtp_recipient_check_complete (smtp_recipient_t recipient); +void *smtp_recipient_get_application_data (smtp_recipient_t recipient); +int smtp_recipient_reset_status (smtp_recipient_t recipient); +void *smtp_recipient_set_application_data (smtp_recipient_t recipient, void *data); +const smtp_status_t *smtp_recipient_status (smtp_recipient_t recipient); +const smtp_status_t *smtp_reverse_path_status (smtp_message_t message); +void *smtp_set_application_data (smtp_session_t session, void *data); +int smtp_set_eventcb (smtp_session_t session, smtp_eventcb_t cb, void *arg); +int smtp_set_header (smtp_message_t message, const char *header, ...); +int smtp_set_header_option (smtp_message_t message, const char *header, enum header_option option, ...); +int smtp_set_hostname (smtp_session_t session, const char *hostname); +int smtp_set_messagecb (smtp_message_t message, smtp_messagecb_t cb, void *arg); +int smtp_set_monitorcb (smtp_session_t session, smtp_monitorcb_t cb, void *arg, int headers); +int smtp_set_resent_headers (smtp_message_t message, int onoff); +int smtp_set_reverse_path (smtp_message_t message, const char *mailbox); +int smtp_set_server (smtp_session_t session, const char *hostport); +int smtp_size_set_estimate (smtp_message_t message, unsigned long size); +int smtp_start_session (smtp_session_t session); +int smtp_starttls_enable (smtp_session_t session, int how); +int smtp_starttls_set_ctx (smtp_session_t session, SSL_CTX *ctx); +char *smtp_strerror (int error, char buf[], size_t buflen); + + + + + Types + +typedef void (*smtp_enumerate_messagecb_t) (smtp_message_t message, void *arg); +typedef void (*smtp_enumerate_recipientcb_t) (smtp_recipient_t recipient, const char *mailbox, void *arg); +typedef void (*smtp_etrn_enumerate_nodecb_t) (smtp_etrn_node_t node, int option, const char *domain, void *arg) +typedef struct smtp_etrn_node *smtp_etrn_node_t; +typedef void (*smtp_eventcb_t) (smtp_session_t session, smtp_message_t message, smtp_recipient_t recipient, int event_no, void *arg); +typedef char *(*smtp_messagecb_t) (char **buf, int *len, void *arg); +typedef struct smtp_message *smtp_message_t; +typedef void (*smtp_monitorcb_t) (const char *buf, int buflen, int writing, void *arg); +typedef struct smtp_recipient *smtp_recipient_t; +typedef struct smtp_session *smtp_session_t; +typedef struct smtp_status smtp_status_t; + + + + + Enumerations + +enum notify_flags; +enum ret_flags; +enum header_option; + + + + + + + + Reference + + +To use the libESMTP API, you must include libesmtp.h in all source +files calling the API functions. + + + +Internally libESMTP creates and maintains three types of structures to +build and track the state of an SMTP protocol session. Pointers +to these structures are passed back to the application by the API and +must be supplied in various other API calls. + + + + Opaque Pointers + +All structures and pointers maintained by libESMTP are opaque, that is, +the internal detail of libESMTP structures is not made available to the +application. + + + + +The pointers are declared as follows. + + + +typedef struct smtp_session *smtp_session_t; +typedef struct smtp_message *smtp_message_t; +typedef struct smtp_recipient *smtp_recipient_t; + + + + Signal Handling + +It is advisable for your application to catch or ignore SIGPIPE. +libESMTP sets timeouts as it progresses through the protocol. In +addition the remote server might close its socket at any time. +Consequently libESMTP may sometimes try to write to a socket with no +reader. Catching or ignoring SIGPIPE ensures the application isn't +killed accidentally when this happens during the protocol session. + + + +Code similar to the following may be used to do this. + + +#include <signal.h> + +void +ignore_sigpipe (void) +{ + struct sigaction sa; + + sa.sa_handler = SIG_IGN; + sigemptyset (&sa.sa_mask); + sa.sa_flags = 0; + sigaction (SIGPIPE, &sa, NULL); +} + + + + + + + + smtp_create_session + create SMTP session descriptor + + + + + + smtp_session_t smtp_create_session + + + + + + + Description + +Create a descriptor which maintains internal state for the SMTP session. + + + + + Return Value + +The descriptor for the SMTP session or NULL on failure. + + + + + + + + + smtp_add_message + add a message to an SMTP session + + + + + + smtp_message_t smtp_add_message + smtp_session_t session + + + + + + Description + +Add a message to the list of messages to be transferred to the remote +MTA during an SMTP session. + + + + + Return Value + +The descriptor for the message state, or NULL on failure. + + + + + + + + + smtp_enumerate_messages + enumerate messages in an SMTP session + + + + + + typedef void (*smtp_enumerate_messagecb_t) + smtp_message_t message + void *arg + + + + + + int smtp_enumerate_messages + smtp_session_t session + smtp_enumerate_messagecb_t cb + void *arg + + + + + + Description + +Call the callback function once for each message in an smtp session. + + + + + Return Value + +Zero on failure, non-zero on success. + + + + + + + + + + smtp_set_hostname + set the name of the localhost + + + + + + int smtp_set_hostname + smtp_session_t session + const char *hostname + + + + + + Description + +Set the name of the localhost. If one is not specified, the local host +name will be determined using uname. + + + + + Return Value + +Zero on failure, non-zero on success. + + + + + + + + + smtp_set_server + set the hostname of the message submission server + + + + + + smtp_set_server + smtp_session_t session + const char *hostport + + + + + + Description + +Set the host name and service for the client connection. This is specified +in the format host.example.org[:service] with no +whitespace surrounding the colon if service is specified. +service may be a name from +/etc/services or a decimal port number. If not +specified the port defaults to 587. Host and service name validity is +not checked until an attempt to connect to the remote host. + + + + + Return Value + +Zero on failure, non-zero on success. + + + + + Notes + +The default port number is set to 587 since this is the port that should +be used for mail submission, see RFC 2476. By choosing this default +now, the API does not change behaviour unexpectedly in the future as +use of the new standard becomes commonplace. The hostport nototion +simplifies things for the application, the user can type +localhost:smtp or +localhost:25 where the application expects a host +name. + + + + + + + + + smtp_set_reverse_path + set the reverse path mailbox + + + + + + smtp_set_reverse_path + smtp_message_t message + const char *mailbox + + + + + + Description + +Set the reverse path (envelope sender) mailbox address. +mailbox must be an address using the syntax +specified in RFC 2821. If a null reverse path is required, specify +mailbox as NULL or +"". + + +If the value is a non-empty string and neither the message contains +a From: header nor a From: is specified using +smtp_set_header, the reverse path mailbox address +specified with this API will be used to generate one. + + +It is strongly reccommended that the message supplies a From: +header specifying a single mailbox or a Sender: header and +a From: header specifying multiple mailboxes or that the +libESMTP header APIs are used to create them. + + + + + Return Value + +Zero on failure, non-zero on success. + + + + + Notes + +Not calling this API has the same effect as specifing +mailbox as NULL. + + + + + + + + + + smtp_add_recipient + add a recipient to a message + + + + + + smtp_recipient_t smtp_add_recipient + smtp_message_t message + const char *mailbox + + + + + + Description + +Add a recipient to the message. mailbox must be an address +using the syntax specified in RFC 2821. + + + +If neither the message contains a To: header nor a +To: is specified using smtp_set_header, a +To: header will be automatically generated using the list +of envelope recipients. + + + +It is strongly reccommended that the message supplies To:, +Cc: and Bcc: headers or that the +libESMTP header APIs are used to create them. + + + + + Return Value + +The descriptor for the recipient state or NULL for failure. + + + + + Notes + +The envelope recipient need not be related to the To/Cc/Bcc +recipients, for example, when a mail is resent to the recipients +of a mailing list or as a result of alias expansion. + + + + + + + + + smtp_enumerate_recipients + enumerate message recipients + + + + + + typedef void (*smtp_enumerate_recipientcb_t) + smtp_recipient_t recipient + const char *mailbox + void *arg + + + + + + int smtp_enumerate_recipients + smtp_message_t message + smtp_enumerate_recipientcb_t cb + void *arg + + + + + + Description + +Call the callback function once for each recipient in the SMTP +message. + + + + + Return Value + +Zero on failure, non-zero on success. + + + + + + + + + smtp_set_header + set an RFC 2822 message header + + + + + + int smtp_set_header + smtp_message_t message + const char *header + ... + + + + + + Description + +Set an RFC 2822 message header. + + +If a value is supplied using smtp_set_header the header +is required to be present in the message. If the Hdr_OVERRIDE +option is not set a value supplied in the message is used unchanged; +otherwise the value in the message is replaced. + + +Headers in the message not corresonding to a default header action or set +with smtp_set_header are passed unchanged. + + + + + Return Value + +Zero on failure, non-zero on success. + + + + + Headers + +This section lists the additional function arguments for individual +RFC 2822 headers. + + + + Function Arguments + + default + + const char *value + +Headers not specifically known to libESMTP are treated as +simple string values. + + + + + + Date: + + const time_t *value + +A pointer to a time_t supplies the value for this header. +The time pointed to is copied and is formatted according to RFC 2822 when +the value is required. + + +The Date: header is automatically generated if one is not +supplied either in the message or via the API. + + + + + + Message-Id: + + const char *value + +A string value is supplied which is the message identifier. +If NULL is supplied, a value is automatically generated. +At present there is no way for the application to retrieve the +automatically generated value. + + + + + + From: + Disposition-Notification-To: + + const char *phrase, const char *mailbox + +phrase is free format text which is usually the +real name of the recipient specified in mailbox, for example +Brian Stafford. + + +mailbox is as defined in RFC 2822, for example +brian@stafford.uklinux.net. + + +The From: header is automatically generated if one is not +supplied either in the message or via the API. +Refer to smtp_set_reverse_path for a +description of the action taken by libESMTP. + + + + + + To: + Cc: + Bcc: + Reply-To: + + const char *phrase, const char *address + +phrase is free format text which is usually the +real name of the recipient specified in address, +for example Brian Stafford. + + +address is as defined in RFC 2822, for example +brian@stafford.uklinux.net. +These headers may be set multiple times, however only one copy of each +header listing all the values is actually created in the message. + + +The To: header is automatically generated if one is not +supplied either in the message or via the API. Refer to +smtp_add_recipient for a description of the action taken +by libESMTP. + + + + + + + + + Notes + +Certain headers may not be set using this call. In particular, MIME +headers cannot be set, the values in the message are always used. +This is because, in the words of RFC 2045, MIME (RFC 2045 - +RFC 2049) is "orthogonal" to RFC 2822 and +libESMTP strives to preserve this condition. +In addition, headers added to a message at delivery time such as +Return-Path: are always deleted from the message. + + +Certain headers may be specified multiple times and generate a single +header listing all values specified. If the header does not permit a +list of values, calls to smtp_set_header but the +first for a given header will fail. + + + + + + + + + smtp_set_header_option + set options for message header processing + + + + + + int smtp_set_header_option + smtp_message_t message + const char *header + enum header_option option + ... + + + + + + Description + +enum header_option + { + Hdr_OVERRIDE, + Hdr_PROHIBIT + }; + + +Set an RFC 2822 message header option. + + + Header Options + + Hdr_OVERRIDE + + +Normally, a header set by smtp_set_header is used +as a default if one is not supplied in the message. When Hdr_OVERRIDE +is set, the value supplied in the API overrides the value in the +message. + + + + + Hdr_PROHIBIT + + +libESMTP generates certain headers automatically if not present in the +message. This is the default behaviour for headers that are RECOMMENDED +but not REQUIRED by RFC 2822, such as Message-Id:. Setting Hdr_PROHIBIT +ensures the transmitted message does not contain the named header. If the +header is REQUIRED by RFC 2822, the API will fail. + + + + + + + + Return Value + +Zero on failure, non-zero on success. + + + + + + + + + smtp_set_resent_headers + + + + smtp_set_resent_headers + + + + + + + int smtp_set_resent_headers + smtp_message_t message + int onoff + + + + + + Description + +Request special processing of headers which have a Resent- +variation. This option is used when resending messages as described in +RFC 2822. + + + + + Return Value + +Zero on failure, non-zero on success. + + + + + + + + + smtp_set_messagecb + set callback for reading the message from an application + + + + + + typedef const char *(smtp_messagecb_t) + void **buf + int *len + void *arg + + + int smtp_set_messagecb + smtp_message_t message + smtp_messagecb_t cb + void *arg + + + + + + Description + +Set a callback function to read an RFC 2822 formatted message +from the application. + + + +The callback is used for two purposes. If len is +set to NULL the callback is to rewind the message. +The return value is not used. If len is not +NULL, the callback returns a pointer to the start +of the message buffer and sets the *len to the +number of octets of data in the buffer. + + + +The callback is called repeatedly until the entire message has +been processed. When all the message data has been read the +callback should return NULL. + + + +If the callback requires a buffer for the message data, it should +allocate one with malloc and place the pointer in *buf, +otherwise *buf must be set to NULL. The buffer is freed +automatically by libESMTP. + + + + + Return Value + +Zero on failure, non-zero on success. + + + + + + + + + smtp_set_eventcb + set callback for reporting events to the applciation + + + + + + typedef void (*smtp_eventcb_t) + smtp_session_t session + int event_no + void *arg + ... + + + + + int smtp_set_eventcb + smtp_session_t session + smtp_eventcb_t cb + void *arg + + + +enum + { + /* Protocol progress */ + SMTP_EV_CONNECT, + SMTP_EV_MAILSTATUS, + SMTP_EV_RCPTSTATUS, + SMTP_EV_MESSAGEDATA, + SMTP_EV_MESSAGESENT, + SMTP_EV_DISCONNECT, + + /* Protocol extension progress */ + SMTP_EV_ETRNSTATUS = 1000, + + /* Required extensions */ + SMTP_EV_EXTNA_DSN = 2000, + SMTP_EV_EXTNA_8BITMIME, + SMTP_EV_EXTNA_STARTTLS, + SMTP_EV_EXTNA_ETRN, + + /* Extensions specific events */ + SMTP_EV_DELIVERBY_EXPIRED = 3000, + + /* STARTTLS */ + SMTP_EV_WEAK_CIPHER = 3100, + SMTP_EV_STARTTLS_OK, + SMTP_EV_INVALID_PEER_CERTIFICATE, + SMTP_EV_NO_PEER_CERTIFICATE, + SMTP_EV_WRONG_PEER_CERTIFICATE + }; + + + + + Description + +Set a callback function to process protocol events during the SMTP session +with the server. The callback function is called when something significant +happens, such as when server, message or recipient status codes are notified. + + + + + Return Value + +Zero on failure, non-zero on success. + + + + + + + + + smtp_set_monitorcb + set callback for tracing the SMTP protocol session + + + + + + typedef void (*smtp_monitorcb_t) + const char *buf + int buflen + int writing + void *arg + + + + + int smtp_set_monitorcb + smtp_session_t session + smtp_monitorcb_t cb + void *arg + int headers + + + +/* Protocol monitor callback. Values for writing */ +#define SMTP_CB_READING 0 +#define SMTP_CB_WRITING 1 +#define SMTP_CB_HEADERS 2 + + + + + Description + +Set a callback function to monitor the SMTP session with the server. +The callback is called with packets of data either transmitted to or +received from the server. When writing is non-zero, data +is being written to the remote host otherwise the data is being read +from the remote host. In the event that an encrypted connection to the +server is in use, the monitor callback will show the clear text. + + +When the callback is used, the data passed in buf +corresponds to the buffered packet of data written to or read from the +server. This may contain more than one protocol command or response. + + +The content of the DATA (or BDAT) command is not passed back to the +application since this is typically large and possibly binary. However, +it may be useful to view the message headers. If +headers is non-zero the callback will be used to +display the message headers. In this case, the value of +writing is set to CB_HEADERS +(2) instead of CB_WRITING (1) so that the +application can distinguish headers from other data sent to the SMTP +server. The callback is passed each header one at a time and in this +case the data passed back to the application does not reflect the actual +buffering of the data on-the-wire. + + +Note that headers within MIME parts will not be returned, +only the message headers. + + + + + Return Value + +Zero on failure, non-zero on success. + + + + + + + + + smtp_set_application_data + attach application data to libESMTP structures + + + + + + void *smtp_set_application_data + smtp_session_t session + void *data + + + + + void *smtp_get_application_data + smtp_session_t session + + + + + void *smtp_message_set_application_data + smtp_message_t message + void *data + + + + + void *smtp_message_get_application_data + smtp_message_t message + + + + + void *smtp_recipient_set_application_data + smtp_recipient_t recipient + void *data + + + + + void *smtp_recipient_get_application_data + smtp_recipient_t recipient + + + + + + Description + +These functions associate application defined data with each of the opaque +structures. The set variants of the functions set a new value for the +application data and return the old value in their respective structures. +The get variants return the current value of the application data. + + + + + Return Value + + + + + + + + + + + smtp_start_session + run an SMTP protocol session + + + + + + int smtp_start_session + smtp_session_t session + + + + + + Description + +Initiate a mail submission session with an SMTP server. + + + +This connects to an SMTP server and transfers the messages in +the session. The SMTP envelope is constructed using the message +and recipient parameters set up previously. The message +callback is then used to read the message contents to the +server. As the RFC 2822 headers are read from the application, +they may be processed. Header processing terminates when the +first line containing only CR-LF is encountered. The remainder of +the message is copied verbatim. + + + +This call is atomic in the sense that a connection to the server +is made only when this is called and is closed down before it +returns, i.e. there is no connection to the server outside this +function. + + + + + Return Value + + + + + + + + + + smtp_destroy_session + release all resources associated with an SMTP session + + + + + + int smtp_destroy_session + smtp_session_t session + + + + + + Description + +Deallocate all resources associated with the SMTP session. + + + + + Return Value + + + + + + + + + + smtp_version + retrieve libESMTP version information + + + + + + int smtp_version + void *buf + size_t len + int what + + + + + + Description + +Retrieve version information for the libESMTP in use. + + + + + Return Value + +Zero on failure, non-zero on success. + + + + + + + + + smtp_errno + get error code for most recent API call + + + + + + int smtp_errno + + + + + + + Description + +Retrieve the error code for the most recently failed API in the +calling thread. + + + + + Return Value + +libESMTP error code. + + + + + + + Error Codes + + +#define SMTP_ERR_NOTHING_TO_DO 2 +#define SMTP_ERR_DROPPED_CONNECTION 3 +#define SMTP_ERR_INVALID_RESPONSE_SYNTAX 4 +#define SMTP_ERR_STATUS_MISMATCH 5 +#define SMTP_ERR_INVALID_RESPONSE_STATUS 6 +#define SMTP_ERR_INVAL 7 +#define SMTP_ERR_EXTENSION_NOT_AVAILABLE 8 + +/* libESMTP versions of some getaddrinfo error numbers */ +#define SMTP_ERR_EAI_ADDRFAMILY 9 +#define SMTP_ERR_EAI_NODATA 10 +#define SMTP_ERR_EAI_FAIL 11 +#define SMTP_ERR_EAI_AGAIN 12 +#define SMTP_ERR_EAI_MEMORY 13 +#define SMTP_ERR_EAI_FAMILY 14 +#define SMTP_ERR_EAI_BADFLAGS 15 +#define SMTP_ERR_EAI_NONAME 16 +#define SMTP_ERR_EAI_SERVICE 17 +#define SMTP_ERR_EAI_SOCKTYPE 18 + + + +SMTP_ERR_INVAL means that an API was called with invalid arguments. + + + + + + + + + smtp_strerror + convert error code to English text + + + + + + const char *smtp_strerror + int error + char buf[] + size_t buflen + + + + + + Description + +Translate a libESMTP error number to a string suitable for use +in an application error message. The resuting string is copied into +buf. + + + + + Return Value + +A pointer to the buf on success or NULL on failure. + + + + + + + + + + SMTP Status codes + + +Functions which retrieve SMTP status codes return a pointer to the following +structure which contains the status information. + + + +struct smtp_status + { + int code; /* SMTP protocol status pre */ + const char *text; /* Text from the server */ + int enh_class; /* RFC 2034 enhanced status triplet */ + int enh_subject; + int enh_detail; + }; +typedef struct smtp_status smtp_status_t; + + + + + + + smtp_message_transfer_status + + + + + + + const smtp_status_t *smtp_message_transfer_status + smtp_message_t message + + + + + + Description + +Retrieve the message transfer success/failure status from a +previous SMTP session. This includes SMTP status codes, RFC +2034 enhanced status codes, if available, and text from the +server describing the status. If a message is marked with a +success or permanent failure status, it will not be resent if +smtp_start_session +is called again. + + + + + Return Value + +NULL if no status information is available, +otherwise a pointer to the status information. The pointer remains +valid until the next call to libESMTP in the same thread. + + + + + + + + + smtp_reverse_path_status + + + + + + + const smtp_status_t *smtp_reverse_path_status + smtp_message_t message + + + + + + Description + +Retrieve the reverse path status from a previous SMTP session. +This includes SMTP status codes, RFC 2034 enhanced status codes, +if available, and text from the server describing the status. + + + + + Return Value + +NULL if no status information is available, otherwise a pointer +to the status information. The pointer remains valid until the +next call to libESMTP in the same thread. + + + + + + + + + smtp_message_reset_status + + + + smtp_message_reset_status + + + + + + + int smtp_message_reset_status + smtp_message_t recipient + + + + + + Description + +Reset the message status to the state it would have before +smtp_start_session is called for the first time on the +containing session. This may be used to force libESMTP to +resend certain messages. + + + + + Return Value + +Zero on failure, non-zero on success. + + + + + + + + + smtp_recipient_status + + + + + + + const smtp_status_t *smtp_recipient_status + smtp_recipient_t recipient + + + + + + Description + +Retrieve the recipient success/failure status from a previous SMTP +session. This includes SMTP status codes, RFC 2034 enhanced status +codes, if available and text from the server describing the status. +If a recipient is marked with a success or permanent failure status, +it will not be resent if smtp_start_session is +called again, however it may be used when generating To: or Cc: headers +if required. + + + + + Return Value + +NULL if no status information is available, otherwise a pointer +to the status information. The pointer remains valid until the +next call to libESMTP in the same thread. + + + + + + + + + smtp_recipient_check_complete + + + + smtp_recipient_check_complete + + + + + + + int smtp_recipient_check_complete + smtp_recipient_t recipient + + + + + + Description + +Check whether processing is complete dor the specified recipient of the +message. Processing is considered complete when an MTA has assumed +responsibility for delivering the message, or if it has indicated a +permanent failure. + + + + + Return Value + +Zero if processing is not complete, non-zero otherwise. + + + + + + + + + smtp_recipient_reset_status + + + + smtp_recipient_reset_status + + + + + + + int smtp_recipient_reset_status + smtp_recipient_t recipient + + + + + + Description + +Reset the recipient status to the state it would have before +smtp_start_session is called for the first time on +the containing session. This is used to force the libESMTP to resend +previously successful recipients. + + + + + Return Value + +Zero on failure, non-zero on success. + + + + + + + + + SMTP Extensions + + +The following APIs relate to SMTP extensions. Note that not all +supported extensions require corresponding API functions. + + + + + RFC 1891. Delivery Status Notification (DSN) + + + + + + + + + smtp_dsn_set_ret + + + + smtp_dsn_set_ret + + + + + + + int smtp_dsn_set_ret + smtp_message_t message + enum ret_flags flags + + + +enum ret_flags { Ret_NOTSET, Ret_FULL, Ret_HDRS }; + + + + + Description + +Instruct the reporting MTA whether to include the full content +of the original message in the Delivery Status Notification, or +just the headers. + + + + + Return Value + +Non zero on success, zero on failure. + + + + + + + + + smtp_dsn_set_envid + + + + smtp_dsn_set_envid + + + + + + + int smtp_dsn_set_envid + smtp_message_t message + const char *envid + + + + + + Description + +Set the envelope identifier. This value is returned in the +DSN and may be used by the MUA to associate the DSN with the +message that caused it to be generated. + + + + + Return Value + +Non zero on success, zero on failure. + + + + + + + + + smtp_dsn_set_notify + + + + smtp_dsn_set_notify + + + + + + + int smtp_dsn_set_notify + smtp_recipient_t recipient + enum notify_flags flags + + + +enum notify_flags + { + Notify_NOTSET, + Notify_NEVER = -1, + Notify_SUCCESS = 1, + Notify_FAILURE = 2, + Notify_DELAY = 4 + }; + + + + + Description + +Set the DSN notify options. Flags may be Notify_NOTSET +or Notify_NEVER or any combination of Notify_SUCCESS, +Notify_FAILURE and Notify_DELAY. + + + + + Return Value + +Non zero on success, zero on failure. + + + + + + + + + smtp_dsn_set_orcpt + + + + smtp_dsn_set_orcpt + + + + + + + int smtp_dsn_set_orcpt + smtp_recipient_t recipient + const char *address_type + const char *address + + + + + + Description + +Set the DSN ORCPT option. + + +Included only for completeness. This DSN option is only used +when performing mailing list expansion or similar situations +when the envelope recipient no longer matches the recipient for +whom the DSN is to be generated. Probably only useful to an MTA +and should not normally be used by an MUA or other program which +submits mail. + + + + + Return Value + +Non zero on success, zero on failure. + + + + + + + + +RFC 1870. SMTP Size Extension. + + + + + + + smtp_size_set_estimate + + + + smtp_size_set_estimate + + + + + + + int smtp_size_set_estimate + smtp_message_t message + unsigned long size + + + + + + Description + +Used by the application to supply an estimate of the size of the +message to be transferred. + + + + + Return Value + +Non zero on success, zero on failure. + + + + + + + + +RFC 1652. SMTP 8bit-MIME Transport Extension + + + + + + + smtp_8bitmime_set_body + + + + smtp_8bitmime_set_body + + + + + + + int smtp_8bitmime_set_body + smtp_message_t message + enum e8bitmime_body body + + + +enum e8bitmime_body + { + E8bitmime_NOTSET, + E8bitmime_7BIT, + E8bitmime_8BITMIME + }; + + + + + Description + +The 8-bit MIME extension allows an SMTP client to declare the message +body is either in strict conformance with RFC 2822 +(E8bitmime_7BIT) or that it is a MIME document +where some or all of the MIME parts use 8bit encoding +(E8bitmime_8BITMIME). If this API sets the body +type to other than E8bitmime_NOTSET, libESMTP will +use the event callback to notify the application if the MTA does not +support the 8BITMIME extension. + + + + + Return Value + +Non zero on success, zero on failure. + + + + + + + + + +RFC 1985. Remote Message Queue Starting (ETRN) + + + +The SMTP ETRN extension is used to request a remore MTA to start its +delivery queue for the specified domain. If the application requests +the use if the ETRN extension and the remote MTA does not list ETRN, +libESMTP will use the event callback to notify the application. + + + + + smtp_etrn_add_node + + + + smtp_etrn_add_node + + + + + +typedef struct smtp_etrn_node *smtp_etrn_node_t; + + + + smtp_etrn_node_t smtp_etrn_add_node + smtp_session_t session + int option + const char *node + + + + + + Description + +Add an ETRN node to the SMTP session. + + + + + Return Value + +The descriptor for the ETRN node, or NULL on failure. + + + + + + + + + smtp_etrn_enumerate_nodes + + + + smtp_etrn_enumerate_nodes + + + + + + + typedef void (*smtp_etrn_enumerate_nodecb_t) + smtp_etrn_node_t node + int option + const char *domain + void *arg + + + + + int smtp_etrn_enumerate_nodes + smtp_session_t session + smtp_etrn_enumerate_nodecb_t cb + void *arg + + + + + + Description + +Call the callback function once for each etrn node in the smtp session. + + + + + Return Value + +Zero on failure, non-zero on success. + + + + + + + + + smtp_etrn_node_status + + + + smtp_etrn_node_status + + + + + + + const smtp_status_t *smtp_etrn_node_status + smtp_etrn_node_t node + + + + + + Description + +Retrieve the ETRN node success/failure status from a previous SMTP +session. This includes SMTP status codes, RFC 2034 enhanced status +codes, if available and text from the server describing the status. + + + + + Return Value + +NULL if no status information is available, +otherwise a pointer to the status information. The pointer remains +valid until the next call to libESMTP in the same thread. + + + + + + + + + smtp_etrn_set_application_data + + + + smtp_etrn_set_application_data + + + + + + + void *smtp_etrn_set_application_data + smtp_etrn_node_t node + void *arg + + + + + void *smtp_etrn_get_application_data + smtp_etrn_node_t node + + + + + + Description + +These functions associate application defined data with the opaque +ETRN structure. The set variant sets a new value for the +application data and returns the old value for the application data. +The get variant returns the current value of the application data. + + + + + Return Value + + + + + + + + + + +RFC 2554. SMTP Auth Extension + + + + + + smtp_auth_set_context + + + + smtp_auth_set_context + + + + + +#include <auth-client.h> +#include <libesmtp.h> + + + + int smtp_auth_set_context + smtp_session_t session + auth_context_t context + + + + + + Description + +Enable the SMTP AUTH verb if context is not +NULL or disable it when context is NULL. +The authentication API is described separately. + + +When enabled and the SMTP server advertises the AUTH extension, libESMTP +will attempt to authenticate to the SMTP server before transferring +any messages. context must be obtained from the SASL (RFC 2222) client +library API defined in auth-client.h. + + + + Authentication Contexts + +A separate authentication context must be created for each SMTP session. +The application is responsible for destroying context. The application +should either call smtp_destroy_session or call +smtp_auth_set_context with context set to +NULL before doing so. + + + + + + Return Value + +Non zero on success, zero on failure. + + + + + + + + +RFC 2487. SMTP StartTLS Extension + + +If OpenSSL is +available when building libESMTP, support for the STARTTLS extension can +be enabled. If support is not enabled, the following APIs will always +fail. + + + + + + + smtp_starttls_enable + + + + smtp_starttls_enable + + + + + +enum starttls_option + { + Starttls_DISABLED, + Starttls_ENABLED, + Starttls_REQUIRED + }; + + + + int smtp_starttls_enable + smtp_session_t session + enum starttls_option how + + + + + + Description + +Enable the SMTP STARTTLS verb if how is not +Starttls_DISABLED. If set +to Starttls_REQUIRED the protocol will quit rather +than transferring any messages if the STARTTLS extension is not +available. + + + + + Return Value + +Non zero on success, zero on failure. + + + + + + + + + smtp_starttls_set_ctx + + + + smtp_starttls_set_ctx + + + + + +#include <openssl/ssl.h> +#include <libesmtp.h> + + + + int smtp_starttls_set_ctx + smtp_session_t session + SSL_CTX *ctx + + + + + + Description + +Use an SSL_CTX created by the application. The +SSL_CTX must be created by the application which is assumed +to have initialised the OpenSSL library. If not used, OpenSSL is +automatically initialised before calling any of the OpenSSL API +functions. + + + + + Return Value + +Non zero on success, zero on failure. + + + + + + +
-- cgit