path: root/doc/api.xml

<?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 &lt;signal.h&gt;

void
ignore_sigpipe (void)
{
  struct sigaction sa;

  sa.sa_handler = SIG_IGN;
  sigemptyset (&amp;sa.sa_mask);
  sa.sa_flags = 0;
  sigaction (SIGPIPE, &amp;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 &quot;orthogonal&quot; 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 &lt;auth-client.h&gt;
#include &lt;libesmtp.h&gt;
      </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 &lt;openssl/ssl.h&gt;
#include &lt;libesmtp.h&gt;
      </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>