diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/api.xml | 2360 |
1 files changed, 2360 insertions, 0 deletions
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 @@ +<?xml version="1.0"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" + "/usr/local/share/docbook-dtd/4.1.2/docbookx.dtd" [ +]> +<article id="index"> + + <articleinfo> + <authorgroup> + <author> + <firstname>Brian</firstname> <surname>Stafford</surname> + <affiliation> + <address> + <email>brian@stafford.uklinux.org</email> + </address> + </affiliation> + </author> + </authorgroup> + + <copyright> + <year>2001,2002</year> + <holder>Brian Stafford</holder> + </copyright> + + <legalnotice> + <para> +Permission is granted to copy, distribute and/or modify this document +under the terms of the <citetitle>GNU Free Documentation +License</citetitle>, 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 +<citetitle>GNU Free Documentation License</citetitle> from the Free +Software Foundation by visiting <ulink type="http" +url="http://www.fsf.org">their Web site</ulink> or by writing to: Free +Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA +02111-1307, USA. + </para> + </legalnotice> + + <title>libESMTP API Reference</title> + + <abstract> + <para> +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). + </para> + </abstract> + </articleinfo> + +<!-- ====================================================================== --> + + <sect1 id="important"> + <title>Important</title> + <para> +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. + </para> + + <para> +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 +<citetitle pubwork="book">The Hitch Hikers' Guide to the Galaxy</citetitle>, +<quote>Much of it is apocryphal or, at the very least, wildly +inaccurate</quote>. However, where it is inaccurate, it is +<quote>definitively inaccurate</quote>. + </para> + + <para> +If in doubt, consult the source. The API and documentation will stabilise +as version 1.0 approaches. + </para> + + <para> + </para> + </sect1> + +<!-- ====================================================================== --> + + <sect1 id="intro"> + <title>Introduction</title> + <para> +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. + </para> + + <para> +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. + </para> + + <para> +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. + </para> + + <para> +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. + </para> + </sect1> + + <sect1 id="smtp-extensions"> + <title>SMTP Extensions</title> + + <para> +libESMTP supports the following SMTP extensions. Those extensions which +are useful only in Message Transport Agents (MTA) will not be implemented +in libESMTP. + </para> + + <itemizedlist> + <listitem><simpara>[RFC 1893] ENHANCEDSTATUSCODES</simpara></listitem> + <listitem><simpara>[RFC 2920] PIPELINING</simpara></listitem> + <listitem><simpara>[RFC 1891] DSN</simpara></listitem> + <listitem><simpara>[RFC 2554] AUTH (SASL)</simpara></listitem> + <listitem><simpara>[RFC 2487] STARTTLS</simpara></listitem> + <listitem><simpara>[RFC 1870] SIZE</simpara></listitem> + <listitem><simpara>[RFC 1985] ETRN</simpara></listitem> + <listitem><simpara>[RFC 1652] 8BITMIME</simpara></listitem> + <listitem><simpara>[RFC 2852] DELIVERBY</simpara></listitem> + </itemizedlist> + + <para> +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. + </para> + + <itemizedlist> + <listitem><simpara>[RFC 3030] CHUNKING</simpara></listitem> + <listitem><simpara>[RFC 3030] BINARYMIME</simpara></listitem> + </itemizedlist> + + <para> +Please note that certain of the SMTP extensions are processed internally +to libESMTP and do not require corresponding API functions. + </para> + </sect1> + + <sect1 id="api"> + <title>API</title> + + <para> +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. + </para> + + <sect2> + <title>Functions</title> + <programlisting> +<!-- smtp_add_message -->smtp_message_t <link linkend="smtp_add_message">smtp_add_message</link> (smtp_session_t session); +<!-- smtp_add_recipient -->smtp_recipient_t <link linkend="smtp_add_recipient">smtp_add_recipient</link> (smtp_message_t message, const char *mailbox); +<!-- smtp_auth_set_context -->int <link linkend="smtp_auth_set_context">smtp_auth_set_context</link> (smtp_session_t session, auth_context_t context); +<!-- smtp_create_session -->smtp_session_t <link linkend="smtp_create_session">smtp_create_session</link> (void); +<!-- smtp_destroy_session -->int <link linkend="smtp_destroy_session">smtp_destroy_session</link> (smtp_session_t session); +<!-- smtp_dsn_set_envid -->int <link linkend="smtp_dsn_set_envid">smtp_dsn_set_envid</link> (smtp_message_t message, const char *envid); +<!-- smtp_dsn_set_notify -->int <link linkend="smtp_dsn_set_notify">smtp_dsn_set_notify</link> (smtp_recipient_t recipient, enum notify_flags flags); +<!-- smtp_dsn_set_orcpt -->int <link linkend="smtp_dsn_set_orcpt">smtp_dsn_set_orcpt</link> (smtp_recipient_t recipient, const char *address_type, const char *address); +<!-- smtp_dsn_set_ret -->int <link linkend="smtp_dsn_set_ret">smtp_dsn_set_ret</link> (smtp_message_t message, enum ret_flags flags); +<!-- smtp_enumerate_messages -->int <link linkend="smtp_enumerate_messages">smtp_enumerate_messages</link> (smtp_session_t session, smtp_enumerate_messagecb_t cb, void *arg); +<!-- smtp_enumerate_recipients -->int <link linkend="smtp_enumerate_recipients">smtp_enumerate_recipients</link> (smtp_message_t message, smtp_enumerate_recipientcb_t cb, void *arg); +<!-- smtp_errno -->int <link linkend="smtp_errno">smtp_errno</link> (void); +<!-- smtp_etrn_add_node -->smtp_etrn_node_t <link linkend="smtp_etrn_add_node">smtp_etrn_add_node</link> (smtp_session_t session, int option, const char *node); +<!-- smtp_etrn_enumerate_nodes -->int <link linkend="smtp_etrn_enumerate_nodes">smtp_etrn_enumerate_nodes</link> (smtp_session_t session, smtp_etrn_enumerate_nodecb_t cb, void *arg); +<!-- smtp_etrn_get_application_data -->void *<link linkend="smtp_etrn_set_application_data">smtp_etrn_get_application_data</link> (smtp_etrn_node_t node); +<!-- smtp_etrn_node_status -->const smtp_status_t *<link linkend="smtp_etrn_node_status">smtp_etrn_node_status</link> (smtp_etrn_node_t node); +<!-- smtp_etrn_set_application_data -->void *<link linkend="smtp_etrn_set_application_data">smtp_etrn_set_application_data</link> (smtp_etrn_node_t node, void *data); +<!-- smtp_get_application_data -->void *<link linkend="smtp_set_application_data">smtp_get_application_data</link> (smtp_session_t session); +<!-- smtp_message_get_application_data -->void *<link linkend="smtp_set_application_data">smtp_message_get_application_data</link> (smtp_message_t message); +<!-- smtp_message_reset_status -->int <link linkend="smtp_message_reset_status">smtp_message_reset_status</link> (smtp_message_t recipient); +<!-- smtp_message_set_application_data -->void *<link linkend="smtp_set_application_data">smtp_message_set_application_data</link> (smtp_message_t message, void *data); +<!-- smtp_message_transfer_status -->const smtp_status_t *<link linkend="smtp_message_transfer_status">smtp_message_transfer_status</link> (smtp_message_t message); +<!-- smtp_recipient_check_complete -->int <link linkend="smtp_recipient_check_complete">smtp_recipient_check_complete</link> (smtp_recipient_t recipient); +<!-- smtp_recipient_get_application_data -->void *<link linkend="smtp_set_application_data">smtp_recipient_get_application_data</link> (smtp_recipient_t recipient); +<!-- smtp_recipient_reset_status -->int <link linkend="smtp_recipient_reset_status">smtp_recipient_reset_status</link> (smtp_recipient_t recipient); +<!-- smtp_recipient_set_application_data -->void *<link linkend="smtp_set_application_data">smtp_recipient_set_application_data</link> (smtp_recipient_t recipient, void *data); +<!-- smtp_recipient_status -->const smtp_status_t *<link linkend="smtp_recipient_status">smtp_recipient_status</link> (smtp_recipient_t recipient); +<!-- smtp_reverse_path_status -->const smtp_status_t *<link linkend="smtp_reverse_path_status">smtp_reverse_path_status</link> (smtp_message_t message); +<!-- smtp_set_application_data -->void *<link linkend="smtp_set_application_data">smtp_set_application_data</link> (smtp_session_t session, void *data); +<!-- smtp_set_eventcb -->int <link linkend="smtp_set_eventcb">smtp_set_eventcb</link> (smtp_session_t session, smtp_eventcb_t cb, void *arg); +<!-- smtp_set_header -->int <link linkend="smtp_set_header">smtp_set_header</link> (smtp_message_t message, const char *header, ...); +<!-- smtp_set_header_option -->int <link linkend="smtp_set_header_option">smtp_set_header_option</link> (smtp_message_t message, const char *header, enum header_option option, ...); +<!-- smtp_set_hostname -->int <link linkend="smtp_set_hostname">smtp_set_hostname</link> (smtp_session_t session, const char *hostname); +<!-- smtp_set_messagecb -->int <link linkend="smtp_set_messagecb">smtp_set_messagecb</link> (smtp_message_t message, smtp_messagecb_t cb, void *arg); +<!-- smtp_set_monitorcb -->int <link linkend="smtp_set_monitorcb">smtp_set_monitorcb</link> (smtp_session_t session, smtp_monitorcb_t cb, void *arg, int headers); +<!-- smtp_set_resent_headers -->int <link linkend="smtp_set_resent_headers">smtp_set_resent_headers</link> (smtp_message_t message, int onoff); +<!-- smtp_set_reverse_path -->int <link linkend="smtp_set_reverse_path">smtp_set_reverse_path</link> (smtp_message_t message, const char *mailbox); +<!-- smtp_set_server -->int <link linkend="smtp_set_server">smtp_set_server</link> (smtp_session_t session, const char *hostport); +<!-- smtp_size_set_estimate -->int <link linkend="smtp_size_set_estimate">smtp_size_set_estimate</link> (smtp_message_t message, unsigned long size); +<!-- smtp_start_session -->int <link linkend="smtp_start_session">smtp_start_session</link> (smtp_session_t session); +<!-- smtp_starttls_enable -->int <link linkend="smtp_starttls_enable">smtp_starttls_enable</link> (smtp_session_t session, int how); +<!-- smtp_starttls_set_ctx -->int <link linkend="smtp_starttls_set_ctx">smtp_starttls_set_ctx</link> (smtp_session_t session, SSL_CTX *ctx); +<!-- smtp_strerror -->char *<link linkend="smtp_strerror">smtp_strerror</link> (int error, char buf[], size_t buflen); + </programlisting> + </sect2> + + <sect2> + <title>Types</title> + <programlisting> +<!-- smtp_enumerate_messagecb_t -->typedef void (*<link linkend="smtp_enumerate_messages">smtp_enumerate_messagecb_t</link>) (smtp_message_t message, void *arg); +<!-- smtp_enumerate_recipientcb_t -->typedef void (*<link linkend="smtp_enumerate_recipients">smtp_enumerate_recipientcb_t</link>) (smtp_recipient_t recipient, const char *mailbox, void *arg); +<!-- smtp_etrn_enumerate_nodecb_t -->typedef void (*<link linkend="smtp_etrn_enumerate_nodes">smtp_etrn_enumerate_nodecb_t</link>) (smtp_etrn_node_t node, int option, const char *domain, void *arg) +<!-- smtp_etrn_node_t -->typedef struct smtp_etrn_node *<link linkend="smtp_etrn_add_node">smtp_etrn_node_t</link>; +<!-- smtp_eventcb_t -->typedef void (*<link linkend="smtp_set_eventcb">smtp_eventcb_t</link>) (smtp_session_t session, smtp_message_t message, smtp_recipient_t recipient, int event_no, void *arg); +<!-- smtp_messagecb_t -->typedef char *(*<link linkend="smtp_set_messagecb">smtp_messagecb_t</link>) (char **buf, int *len, void *arg); +<!-- smtp_message_t -->typedef struct smtp_message *<link linkend="smtp_message_t">smtp_message_t</link>; +<!-- smtp_monitorcb_t -->typedef void (*<link linkend="smtp_set_monitorcb">smtp_monitorcb_t</link>) (const char *buf, int buflen, int writing, void *arg); +<!-- smtp_recipient_t -->typedef struct smtp_recipient *<link linkend="smtp_recipient_t">smtp_recipient_t</link>; +<!-- smtp_session_t -->typedef struct smtp_session *<link linkend="smtp_session_t">smtp_session_t</link>; +<!-- smtp_status_t -->typedef struct smtp_status <link linkend="smtp_status_t">smtp_status_t</link>; + </programlisting> + </sect2> + + <sect2> + <title>Enumerations</title> + <programlisting> +enum <link linkend="smtp_dsn_set_notify">notify_flags</link>; +enum <link linkend="smtp_dsn_set_ret">ret_flags</link>; +enum <link linkend="smtp_set_header_option">header_option</link>; + </programlisting> + </sect2> + </sect1> + +<!-- ====================================================================== --> + + <sect1 id="reference"> + <title>Reference</title> + + <para> +To use the libESMTP API, you must include libesmtp.h in all source +files calling the API functions. + </para> + + <para> +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. + </para> + + <note> + <title>Opaque Pointers</title> + <para> +All structures and pointers maintained by libESMTP are opaque, that is, +the internal detail of libESMTP structures is not made available to the +application. + </para> + </note> + + <para> +The pointers are declared as follows. + </para> + + <programlisting> +typedef struct smtp_session *<anchor id="smtp_session_t"/>smtp_session_t; +typedef struct smtp_message *<anchor id="smtp_message_t"/>smtp_message_t; +typedef struct smtp_recipient *<anchor id="smtp_recipient_t"/>smtp_recipient_t; + </programlisting> + + <important> + <title>Signal Handling</title> + <para> +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. + </para> + + <para> +Code similar to the following may be used to do this. + </para> + <programlisting> +#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); +} + </programlisting> + </important> + +<!-- ====================================================================== --> + + <refentry id="smtp_create_session"> + <refnamediv> + <refname>smtp_create_session</refname> + <refpurpose>create SMTP session descriptor</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>smtp_session_t <function>smtp_create_session</function></funcdef> + <void/> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Create a descriptor which maintains internal state for the SMTP session. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +The descriptor for the SMTP session or <constant>NULL</constant> on failure. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_add_message"> + <refnamediv> + <refname>smtp_add_message</refname> + <refpurpose>add a message to an SMTP session</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>smtp_message_t <function>smtp_add_message</function></funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Add a message to the list of messages to be transferred to the remote +MTA during an SMTP session. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +The descriptor for the message state, or <constant>NULL</constant> on failure. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_enumerate_messages"> + <refnamediv> + <refname>smtp_enumerate_messages</refname> + <refpurpose>enumerate messages in an SMTP session</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>typedef void <function>(*smtp_enumerate_messagecb_t)</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + <paramdef>void *<parameter>arg</parameter></paramdef> + </funcprototype> + </funcsynopsis> + + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_enumerate_messages</function></funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + <paramdef>smtp_enumerate_messagecb_t <parameter>cb</parameter></paramdef> + <paramdef>void *<parameter></parameter>arg</paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Call the callback function once for each message in an smtp session. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero on failure, non-zero on success. + </para> + </refsect1> + </refentry> + + +<!-- ====================================================================== --> + + <refentry id="smtp_set_hostname"> + <refnamediv> + <refname>smtp_set_hostname</refname> + <refpurpose>set the name of the localhost</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_set_hostname</function></funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + <paramdef>const char *<parameter>hostname</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Set the name of the localhost. If one is not specified, the local host +name will be determined using <function>uname</function>. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero on failure, non-zero on success. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_set_server"> + <refnamediv> + <refname>smtp_set_server</refname> + <refpurpose>set the hostname of the message submission server</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef><function>smtp_set_server</function></funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + <paramdef>const char *<parameter>hostport</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Set the host name and service for the client connection. This is specified +in the format <userinput>host.example.org[:service]</userinput> with no +whitespace surrounding the colon if <token>service</token> is specified. +<token>service</token> may be a name from +<filename>/etc/services</filename> 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. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero on failure, non-zero on success. + </para> + </refsect1> + + <refsect1> + <title>Notes</title> + <para> +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 +<userinput>localhost:smtp</userinput> or +<userinput>localhost:25</userinput> where the application expects a host +name. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_set_reverse_path"> + <refnamediv> + <refname>smtp_set_reverse_path</refname> + <refpurpose>set the reverse path mailbox</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef><function>smtp_set_reverse_path</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + <paramdef>const char *<parameter>mailbox</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Set the reverse path (envelope sender) mailbox address. +<parameter>mailbox</parameter> must be an address using the syntax +specified in RFC 2821. If a null reverse path is required, specify +<parameter>mailbox</parameter> as <constant>NULL</constant> or +<constant>""</constant>. + </para> + <para> +If the value is a non-empty string and neither the message contains +a From: header nor a From: is specified using +<function>smtp_set_header</function>, the reverse path mailbox address +specified with this API will be used to generate one. + </para> + <para> +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. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero on failure, non-zero on success. + </para> + </refsect1> + + <refsect1> + <title>Notes</title> + <para> +Not calling this API has the same effect as specifing +<parameter>mailbox</parameter> as <constant>NULL</constant>. + </para> + </refsect1> + </refentry> + + +<!-- ====================================================================== --> + + <refentry id="smtp_add_recipient"> + <refnamediv> + <refname>smtp_add_recipient</refname> + <refpurpose>add a recipient to a message</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>smtp_recipient_t <function>smtp_add_recipient</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + <paramdef>const char *<parameter>mailbox</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Add a recipient to the message. <parameter>mailbox</parameter> must be an address +using the syntax specified in RFC 2821. + </para> + + <para> +If neither the message contains a To: header nor a +To: is specified using <function>smtp_set_header</function>, a +To: header will be automatically generated using the list +of envelope recipients. + </para> + + <para> +It is strongly reccommended that the message supplies To:, +Cc: and Bcc: headers or that the +libESMTP header APIs are used to create them. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +The descriptor for the recipient state or <constant>NULL</constant> for failure. + </para> + </refsect1> + + <refsect1> + <title>Notes</title> + <para> +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. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_enumerate_recipients"> + <refnamediv> + <refname>smtp_enumerate_recipients</refname> + <refpurpose>enumerate message recipients</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>typedef void (*<function>smtp_enumerate_recipientcb_t</function>)</funcdef> + <paramdef>smtp_recipient_t <parameter>recipient</parameter></paramdef> + <paramdef>const char *<parameter>mailbox</parameter></paramdef> + <paramdef>void *<parameter>arg</parameter></paramdef> + </funcprototype> + </funcsynopsis> + + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_enumerate_recipients</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + <paramdef>smtp_enumerate_recipientcb_t <parameter>cb</parameter></paramdef> + <paramdef>void *<parameter>arg</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Call the callback function once for each recipient in the SMTP +message. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero on failure, non-zero on success. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_set_header"> + <refnamediv> + <refname>smtp_set_header</refname> + <refpurpose>set an RFC 2822 message header</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_set_header</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + <paramdef>const char *<parameter>header</parameter></paramdef> + <paramdef><parameter>...</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Set an RFC 2822 message header. + </para> + <para> +If a value is supplied using <function>smtp_set_header</function> the header +is required to be present in the message. If the <constant>Hdr_OVERRIDE</constant> +option is not set a value supplied in the message is used unchanged; +otherwise the value in the message is replaced. + </para> + <para> +Headers in the message not corresonding to a default header action or set +with <function>smtp_set_header</function> are passed unchanged. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero on failure, non-zero on success. + </para> + </refsect1> + + <refsect1> + <title>Headers</title> + <para> +This section lists the additional function arguments for individual +RFC 2822 headers. + </para> + + <variablelist> + <title>Function Arguments</title> + <varlistentry> + <term>default</term> + <listitem> + <programlisting>const char *value</programlisting> + <para> +Headers not specifically known to libESMTP are treated as +simple string values. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Date:</term> + <listitem> + <programlisting>const time_t *value</programlisting> + <para> +A pointer to a <type>time_t</type> supplies the value for this header. +The time pointed to is copied and is formatted according to RFC 2822 when +the value is required. + </para> + <para> +The Date: header is automatically generated if one is not +supplied either in the message or via the API. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Message-Id:</term> + <listitem> + <programlisting>const char *value</programlisting> + <para> +A string value is supplied which is the message identifier. +If <constant>NULL</constant> is supplied, a value is automatically generated. +At present there is no way for the application to retrieve the +automatically generated value. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>From:</term> + <term>Disposition-Notification-To:</term> + <listitem> + <programlisting>const char *phrase, const char *mailbox</programlisting> + <para> +<parameter>phrase</parameter> is free format text which is usually the +real name of the recipient specified in <parameter>mailbox</parameter>, for example +Brian Stafford. + </para> + <para> +<parameter>mailbox</parameter> is as defined in RFC 2822, for example +brian@stafford.uklinux.net. + </para> + <para> +The From: header is automatically generated if one is not +supplied either in the message or via the API. +Refer to <function>smtp_set_reverse_path</function> for a +description of the action taken by libESMTP. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>To:</term> + <term>Cc:</term> + <term>Bcc:</term> + <term>Reply-To:</term> + <listitem> + <programlisting>const char *phrase, const char *address</programlisting> + <para> +<parameter>phrase</parameter> is free format text which is usually the +real name of the recipient specified in <parameter>address</parameter>, +for example Brian Stafford. + </para> + <para> +<parameter>address</parameter> 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. + </para> + <para> +The To: header is automatically generated if one is not +supplied either in the message or via the API. Refer to +<function>smtp_add_recipient</function> for a description of the action taken +by libESMTP. + </para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Notes</title> + <para> +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. + </para> + <para> +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 <function>smtp_set_header</function> but the +first for a given header will fail. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_set_header_option"> + <refnamediv> + <refname>smtp_set_header_option</refname> + <refpurpose>set options for message header processing</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_set_header_option</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + <paramdef>const char *<parameter>header</parameter></paramdef> + <paramdef>enum header_option <parameter>option</parameter></paramdef> + <paramdef><parameter>...</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <programlisting> +enum header_option + { + Hdr_OVERRIDE, + Hdr_PROHIBIT + }; + </programlisting> + <para> +Set an RFC 2822 message header option. + </para> + <variablelist> + <title>Header Options</title> + <varlistentry> + <term>Hdr_OVERRIDE</term> + <listitem> + <para> +Normally, a header set by <function>smtp_set_header</function> 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. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Hdr_PROHIBIT</term> + <listitem> + <para> +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. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero on failure, non-zero on success. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_set_resent_headers"> + <refmeta> + <refentrytitle>smtp_set_resent_headers</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_set_resent_headers</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_set_resent_headers</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + <paramdef>int <parameter>onoff</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Request special processing of headers which have a Resent- +variation. This option is used when resending messages as described in +RFC 2822. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero on failure, non-zero on success. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_set_messagecb"> + <refnamediv> + <refname>smtp_set_messagecb</refname> + <refpurpose>set callback for reading the message from an application</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>typedef const char *(<function>smtp_messagecb_t</function>)</funcdef> + <paramdef>void **<parameter>buf</parameter></paramdef> + <paramdef>int *<parameter>len</parameter></paramdef> + <paramdef>void *<parameter>arg</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>smtp_set_messagecb</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + <paramdef>smtp_messagecb_t <parameter>cb</parameter></paramdef> + <paramdef>void *<parameter>arg</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Set a callback function to read an RFC 2822 formatted message +from the application. + </para> + + <para> +The callback is used for two purposes. If <parameter>len</parameter> is +set to <constant>NULL</constant> the callback is to rewind the message. +The return value is not used. If <parameter>len</parameter> is not +<constant>NULL</constant>, the callback returns a pointer to the start +of the message buffer and sets the <parameter>*len</parameter> to the +number of octets of data in the buffer. + </para> + + <para> +The callback is called repeatedly until the entire message has +been processed. When all the message data has been read the +callback should return <constant>NULL</constant>. + </para> + + <para> +If the callback requires a buffer for the message data, it should +allocate one with malloc and place the pointer in <parameter>*buf</parameter>, +otherwise <parameter>*buf</parameter> must be set to <constant>NULL</constant>. The buffer is freed +automatically by libESMTP. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero on failure, non-zero on success. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_set_eventcb"> + <refnamediv> + <refname>smtp_set_eventcb</refname> + <refpurpose>set callback for reporting events to the applciation</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>typedef void (*<function>smtp_eventcb_t</function>)</funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + <paramdef>int <parameter>event_no</parameter></paramdef> + <paramdef>void *<parameter>arg</parameter></paramdef> + <paramdef><parameter>...</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_set_eventcb</function></funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + <paramdef>smtp_eventcb_t <parameter>cb</parameter></paramdef> + <paramdef>void *<parameter>arg</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <programlisting> +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 + }; + </programlisting> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +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. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero on failure, non-zero on success. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_set_monitorcb"> + <refnamediv> + <refname>smtp_set_monitorcb</refname> + <refpurpose>set callback for tracing the SMTP protocol session</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>typedef void (*<function>smtp_monitorcb_t</function>)</funcdef> + <paramdef>const char *<parameter>buf</parameter></paramdef> + <paramdef>int <parameter>buflen</parameter></paramdef> + <paramdef>int <parameter>writing</parameter></paramdef> + <paramdef>void *<parameter>arg</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_set_monitorcb</function></funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + <paramdef>smtp_monitorcb_t <parameter>cb</parameter></paramdef> + <paramdef>void *<parameter>arg</parameter></paramdef> + <paramdef>int <parameter>headers</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <programlisting> +/* Protocol monitor callback. Values for writing */ +#define SMTP_CB_READING 0 +#define SMTP_CB_WRITING 1 +#define SMTP_CB_HEADERS 2 + </programlisting> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +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. + </para> + <para> +When the callback is used, the data passed in <parameter>buf</parameter> +corresponds to the buffered packet of data written to or read from the +server. This may contain more than one protocol command or response. + </para> + <para> +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 +<parameter>headers</parameter> is non-zero the callback will be used to +display the message headers. In this case, the value of +<parameter>writing</parameter> is set to <constant>CB_HEADERS</constant> +(2) instead of <constant>CB_WRITING</constant> (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. + </para> + <para> +Note that headers within MIME parts will not be returned, +only the message headers. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero on failure, non-zero on success. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_set_application_data"> + <refnamediv> + <refname>smtp_set_application_data</refname> + <refpurpose>attach application data to libESMTP structures</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>void *<function>smtp_set_application_data</function></funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + <paramdef>void *<parameter>data</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <funcsynopsis> + <funcprototype> + <funcdef>void *<function>smtp_get_application_data</function></funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <funcsynopsis> + <funcprototype> + <funcdef>void *<function>smtp_message_set_application_data</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + <paramdef>void *<parameter>data</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <funcsynopsis> + <funcprototype> + <funcdef>void *<function>smtp_message_get_application_data</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <funcsynopsis> + <funcprototype> + <funcdef>void *<function>smtp_recipient_set_application_data</function></funcdef> + <paramdef>smtp_recipient_t <parameter>recipient</parameter></paramdef> + <paramdef>void *<parameter>data</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <funcsynopsis> + <funcprototype> + <funcdef>void *<function>smtp_recipient_get_application_data</function></funcdef> + <paramdef>smtp_recipient_t <parameter>recipient</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +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. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> + </para> + </refsect1> + </refentry> + + +<!-- ====================================================================== --> + + <refentry id="smtp_start_session"> + <refnamediv> + <refname>smtp_start_session</refname> + <refpurpose>run an SMTP protocol session</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_start_session</function></funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Initiate a mail submission session with an SMTP server. + </para> + + <para> +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. + </para> + + <para> +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. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_destroy_session"> + <refnamediv> + <refname>smtp_destroy_session</refname> + <refpurpose>release all resources associated with an SMTP session</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_destroy_session</function></funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Deallocate all resources associated with the SMTP session. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_version"> + <refnamediv> + <refname>smtp_version</refname> + <refpurpose>retrieve libESMTP version information</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_version</function></funcdef> + <paramdef>void *<parameter>buf</parameter></paramdef> + <paramdef>size_t <parameter>len</parameter></paramdef> + <paramdef>int <parameter>what</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Retrieve version information for the libESMTP in use. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero on failure, non-zero on success. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_errno"> + <refnamediv> + <refname>smtp_errno</refname> + <refpurpose>get error code for most recent API call</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_errno</function></funcdef> + <paramdef><parameter></parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Retrieve the error code for the most recently failed API in the +calling thread. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +libESMTP error code. + </para> + </refsect1> + +<!-- ====================================================================== --> + + <refsect1 id="errorcodes"> + <title>Error Codes</title> + + <programlisting> +#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 + </programlisting> + + <para> +SMTP_ERR_INVAL means that an API was called with invalid arguments. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_strerror"> + <refnamediv> + <refname>smtp_strerror</refname> + <refpurpose>convert error code to English text</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>const char *<function>smtp_strerror</function></funcdef> + <paramdef>int <parameter>error</parameter></paramdef> + <paramdef>char <parameter>buf</parameter>[]</paramdef> + <paramdef>size_t <parameter>buflen</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Translate a libESMTP error number to a string suitable for use +in an application error message. The resuting string is copied into +<parameter>buf</parameter>. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +A pointer to the <parameter>buf</parameter> on success or NULL on failure. + </para> + </refsect1> + </refentry> + + </sect1> + +<!-- ====================================================================== --> + + <sect1 id="smtp_status_t"> + <title>SMTP Status codes</title> + + <para> +Functions which retrieve SMTP status codes return a pointer to the following +structure which contains the status information. + </para> + + <programlisting> +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; + </programlisting> + +<!-- ====================================================================== --> + + <refentry id="smtp_message_transfer_status"> + <refnamediv> + <refname>smtp_message_transfer_status</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>const smtp_status_t *<function>smtp_message_transfer_status</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +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 +<function>smtp_start_session</function> +is called again. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +<constant>NULL</constant> 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. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_reverse_path_status"> + <refnamediv> + <refname>smtp_reverse_path_status</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>const smtp_status_t *<function>smtp_reverse_path_status</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +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. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +<constant>NULL</constant> 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. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_message_reset_status"> + <refmeta> + <refentrytitle>smtp_message_reset_status</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_message_reset_status</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_message_reset_status</function></funcdef> + <paramdef>smtp_message_t <parameter>recipient</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Reset the message status to the state it would have before +<function>smtp_start_session</function> is called for the first time on the +containing session. This may be used to force libESMTP to +resend certain messages. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero on failure, non-zero on success. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_recipient_status"> + <refnamediv> + <refname>smtp_recipient_status</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>const smtp_status_t *<function>smtp_recipient_status</function></funcdef> + <paramdef>smtp_recipient_t <parameter>recipient</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +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 <function>smtp_start_session</function> is +called again, however it may be used when generating To: or Cc: headers +if required. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +<constant>NULL</constant> 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. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_recipient_check_complete"> + <refmeta> + <refentrytitle>smtp_recipient_check_complete</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_recipient_check_complete</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_recipient_check_complete</function></funcdef> + <paramdef>smtp_recipient_t <parameter>recipient</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +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. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero if processing is not complete, non-zero otherwise. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_recipient_reset_status"> + <refmeta> + <refentrytitle>smtp_recipient_reset_status</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_recipient_reset_status</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_recipient_reset_status</function></funcdef> + <paramdef>smtp_recipient_t <parameter>recipient</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Reset the recipient status to the state it would have before +<function>smtp_start_session</function> is called for the first time on +the containing session. This is used to force the libESMTP to resend +previously successful recipients. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero on failure, non-zero on success. + </para> + </refsect1> + </refentry> + + </sect1> +<!-- ====================================================================== --> + + <sect1 id="extensions"> + <title>SMTP Extensions</title> + + <para> +The following APIs relate to SMTP extensions. Note that not all +supported extensions require corresponding API functions. + </para> + </sect1> + + <sect1 id="dsn"> + <title>RFC 1891. Delivery Status Notification (DSN)</title> + + <para> + </para> + +<!-- ====================================================================== --> + + <refentry id="smtp_dsn_set_ret"> + <refmeta> + <refentrytitle>smtp_dsn_set_ret</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_dsn_set_ret</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_dsn_set_ret</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + <paramdef>enum ret_flags <parameter>flags</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <programlisting> +enum ret_flags { Ret_NOTSET, Ret_FULL, Ret_HDRS }; + </programlisting> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Instruct the reporting MTA whether to include the full content +of the original message in the Delivery Status Notification, or +just the headers. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Non zero on success, zero on failure. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_dsn_set_envid"> + <refmeta> + <refentrytitle>smtp_dsn_set_envid</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_dsn_set_envid</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_dsn_set_envid</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + <paramdef>const char *<parameter>envid</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +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. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Non zero on success, zero on failure. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_dsn_set_notify"> + <refmeta> + <refentrytitle>smtp_dsn_set_notify</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_dsn_set_notify</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_dsn_set_notify</function></funcdef> + <paramdef>smtp_recipient_t <parameter>recipient</parameter></paramdef> + <paramdef>enum notify_flags <parameter>flags</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <programlisting> +enum notify_flags + { + Notify_NOTSET, + Notify_NEVER = -1, + Notify_SUCCESS = 1, + Notify_FAILURE = 2, + Notify_DELAY = 4 + }; + </programlisting> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Set the DSN notify options. Flags may be Notify_NOTSET +or Notify_NEVER or any combination of Notify_SUCCESS, +Notify_FAILURE and Notify_DELAY. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Non zero on success, zero on failure. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_dsn_set_orcpt"> + <refmeta> + <refentrytitle>smtp_dsn_set_orcpt</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_dsn_set_orcpt</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_dsn_set_orcpt</function></funcdef> + <paramdef>smtp_recipient_t <parameter>recipient</parameter></paramdef> + <paramdef>const char *<parameter>address_type</parameter></paramdef> + <paramdef>const char *<parameter>address</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Set the DSN ORCPT option. + </para> + <para> +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. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Non zero on success, zero on failure. + </para> + </refsect1> + </refentry> + + </sect1> +<!-- ====================================================================== --> + +<sect1 id="size"> +<title>RFC 1870. SMTP Size Extension.</title> + + <para> + </para> + + <refentry id="smtp_size_set_estimate"> + <refmeta> + <refentrytitle>smtp_size_set_estimate</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_size_set_estimate</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_size_set_estimate</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + <paramdef>unsigned long <parameter>size</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Used by the application to supply an estimate of the size of the +message to be transferred. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Non zero on success, zero on failure. + </para> + </refsect1> + </refentry> + +</sect1> +<!-- ====================================================================== --> + +<sect1 id="e8bitmime"> +<title>RFC 1652. SMTP 8bit-MIME Transport Extension</title> + + <para> + </para> + + <refentry id="smtp_8bitmime_set_body"> + <refmeta> + <refentrytitle>smtp_8bitmime_set_body</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_8bitmime_set_body</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_8bitmime_set_body</function></funcdef> + <paramdef>smtp_message_t <parameter>message</parameter></paramdef> + <paramdef>enum e8bitmime_body <parameter>body</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <programlisting> +enum e8bitmime_body + { + E8bitmime_NOTSET, + E8bitmime_7BIT, + E8bitmime_8BITMIME + }; + </programlisting> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +The 8-bit MIME extension allows an SMTP client to declare the message +body is either in strict conformance with RFC 2822 +(<constant>E8bitmime_7BIT</constant>) or that it is a MIME document +where some or all of the MIME parts use 8bit encoding +(<constant>E8bitmime_8BITMIME</constant>). If this API sets the body +type to other than <constant>E8bitmime_NOTSET</constant>, libESMTP will +use the event callback to notify the application if the MTA does not +support the 8BITMIME extension. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Non zero on success, zero on failure. + </para> + </refsect1> + </refentry> + +</sect1> + +<!-- ====================================================================== --> + +<sect1 id="etrn"> +<title>RFC 1985. Remote Message Queue Starting (ETRN)</title> + + +<para> +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. +</para> + + <refentry id="smtp_etrn_add_node"> + <refmeta> + <refentrytitle>smtp_etrn_add_node</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_etrn_add_node</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <programlisting> +typedef struct smtp_etrn_node *smtp_etrn_node_t; + </programlisting> + <funcsynopsis> + <funcprototype> + <funcdef>smtp_etrn_node_t <function>smtp_etrn_add_node</function></funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + <paramdef>int <parameter>option</parameter></paramdef> + <paramdef>const char *<parameter>node</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Add an ETRN node to the SMTP session. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +The descriptor for the ETRN node, or <constant>NULL</constant> on failure. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_etrn_enumerate_nodes"> + <refmeta> + <refentrytitle>smtp_etrn_enumerate_nodes</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_etrn_enumerate_nodes</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>typedef void (*<function>smtp_etrn_enumerate_nodecb_t</function>)</funcdef> + <paramdef>smtp_etrn_node_t <parameter>node</parameter></paramdef> + <paramdef>int <parameter>option</parameter></paramdef> + <paramdef>const char *<parameter>domain</parameter></paramdef> + <paramdef>void *<parameter>arg</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_etrn_enumerate_nodes</function></funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + <paramdef>smtp_etrn_enumerate_nodecb_t <parameter>cb</parameter></paramdef> + <paramdef>void *<parameter>arg</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Call the callback function once for each etrn node in the smtp session. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Zero on failure, non-zero on success. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_etrn_node_status"> + <refmeta> + <refentrytitle>smtp_etrn_node_status</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_etrn_node_status</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>const smtp_status_t *<function>smtp_etrn_node_status</function></funcdef> + <paramdef>smtp_etrn_node_t <parameter>node</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +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. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +<constant>NULL</constant> 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. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_etrn_set_application_data"> + <refmeta> + <refentrytitle>smtp_etrn_set_application_data</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_etrn_set_application_data</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <funcsynopsis> + <funcprototype> + <funcdef>void *<function>smtp_etrn_set_application_data</function></funcdef> + <paramdef>smtp_etrn_node_t <parameter>node</parameter></paramdef> + <paramdef>void *<parameter>arg</parameter></paramdef> + </funcprototype> + </funcsynopsis> + <funcsynopsis> + <funcprototype> + <funcdef>void *<function>smtp_etrn_get_application_data</function></funcdef> + <paramdef>smtp_etrn_node_t <parameter>node</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +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. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> + </para> + </refsect1> + </refentry> + +</sect1> + +<!-- ====================================================================== --> + +<sect1 id="auth"> +<title>RFC 2554. SMTP Auth Extension</title> +<para> +</para> + + <refentry id="smtp_auth_set_context"> + <refmeta> + <refentrytitle>smtp_auth_set_context</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_auth_set_context</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <programlisting> +#include <auth-client.h> +#include <libesmtp.h> + </programlisting> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_auth_set_context</function></funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + <paramdef>auth_context_t <parameter>context</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Enable the SMTP AUTH verb if <parameter>context</parameter> is not +<constant>NULL</constant> or disable it when context is <constant>NULL</constant>. +The authentication API is described separately. + </para> + <para> +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 <filename>auth-client.h</filename>. + </para> + + <note> + <title>Authentication Contexts</title> + <para> +A separate authentication context must be created for each SMTP session. +The application is responsible for destroying context. The application +should either call <function>smtp_destroy_session</function> or call +<function>smtp_auth_set_context</function> with context set to +<constant>NULL</constant> before doing so. + </para> + </note> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Non zero on success, zero on failure. + </para> + </refsect1> + </refentry> + +</sect1> +<!-- ====================================================================== --> + +<sect1 id="starttls"> +<title>RFC 2487. SMTP StartTLS Extension</title> + +<para> +If <ulink type="http" url="http://www.openssl.org/">OpenSSL</ulink> is +available when building libESMTP, support for the STARTTLS extension can +be enabled. If support is not enabled, the following APIs will always +fail. +</para> + +<!-- ====================================================================== --> + + <refentry id="smtp_starttls_enable"> + <refmeta> + <refentrytitle>smtp_starttls_enable</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_starttls_enable</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <programlisting> +enum starttls_option + { + Starttls_DISABLED, + Starttls_ENABLED, + Starttls_REQUIRED + }; + </programlisting> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_starttls_enable</function></funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + <paramdef>enum starttls_option <parameter>how</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Enable the SMTP STARTTLS verb if <parameter>how</parameter> is not +<constant>Starttls_DISABLED</constant>. If set +to <constant>Starttls_REQUIRED</constant> the protocol will quit rather +than transferring any messages if the STARTTLS extension is not +available. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Non zero on success, zero on failure. + </para> + </refsect1> + </refentry> + +<!-- ====================================================================== --> + + <refentry id="smtp_starttls_set_ctx"> + <refmeta> + <refentrytitle>smtp_starttls_set_ctx</refentrytitle> + </refmeta> + + <refnamediv> + <refname>smtp_starttls_set_ctx</refname> + <refpurpose></refpurpose> + </refnamediv> + + <refsynopsisdiv> + <programlisting> +#include <openssl/ssl.h> +#include <libesmtp.h> + </programlisting> + <funcsynopsis> + <funcprototype> + <funcdef>int <function>smtp_starttls_set_ctx</function></funcdef> + <paramdef>smtp_session_t <parameter>session</parameter></paramdef> + <paramdef>SSL_CTX *<parameter>ctx</parameter></paramdef> + </funcprototype> + </funcsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + <para> +Use an <type>SSL_CTX</type> created by the application. The +<type>SSL_CTX</type> 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. + </para> + </refsect1> + + <refsect1> + <title>Return Value</title> + <para> +Non zero on success, zero on failure. + </para> + </refsect1> + </refentry> + +</sect1> + +</article> |