<?xml version="1.0" encoding="UTF-8"?>

<!-- ====================================================================== -->
<!-- = appendix-ii.xml                                                    = -->
<!-- = standard network module guide - appendix ii                        = -->
<!-- ====================================================================== -->
<!-- = This  program  is  free  software; you  can redistribute it and/or = -->
<!-- = modify it provided that this copyright notice is kept intact.      = -->
<!-- = This program is distributed in the hope that it will be useful but = -->
<!-- = without  any  warranty;  without  even  the  implied  warranty  of = -->
<!-- = merchantability or fitness for  a  particular purpose. In no event = -->
<!-- = shall  the  copyright  holder be liable for any  direct, indirect, = -->
<!-- = incidental  or special  damages arising  in any way out of the use = -->
<!-- = of this software.                                                  = -->
<!-- ====================================================================== -->
<!-- = copyright (c) 2005-2007 - amaury darsch                            = -->
<!-- ====================================================================== -->

<appendix module="net" number="ii">
  <title>Mail services reference</title>

  <p>
  This appendix is a reference of the <afnix/> standard networking
  module mail services subsystem.
  </p>

  <table>
    <title>Standard networking module</title>
    <thead>
      <tr><td>Symbol</td> <td>Description</td></tr>
    </thead>
    <tbody>
      <tr><td>afnix-net</td><td>module</td></tr>
      <tr><td>afnix:net</td><td>nameset</td></tr>
    </tbody>
  </table>

  <!-- =================================================================== -->
  <!-- = mail object                                                     = -->
  <!-- =================================================================== -->

  <object nameset="afnix:net">
    <name>Mail</name>

    <!-- synopsis -->
    <p>
    The <code>Mail</code> class is a mail delivery object which
    manages to contact a <em>Mail Transport Agent</em> or MTA in order
    to deliver a message to one or several recipients. By default, the
    object contacts the local MTA, but this behavior can be changed
    with the <code>set-mta-address</code> method. The class implements
    the recipient an address syntax scheme as specified by RFC822. At
    construction, the instance is empty. Only the recipient address
    needs to be specified. The <code>send</code> method send the
    message by contacting the MTA. If an error occurs, an exception is
    raised.
    </p>

    <!-- predicate -->
    <pred>mail-p</pred>

    <!-- inheritance -->
    <inherit>
      <name>Object</name>
    </inherit>

    <!-- constructor -->
    <ctor>
      <name>Mail</name>
      <args>none</args>
      <p>
      The <code>Mail</code> constructor create a a default message
      which is empty. The recipient addresses and the subject must be
      specified for a successful message delivery.
      </p>
    </ctor>

    <!-- methods -->
    <method>
      <name>to</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>to</code> method adds one or several address to the
      <em>destination list</em>. The address format must conform to
      RFC822. Multiple address are coma separated. Multiple call to this
      method is possible.
      </p>
    </method>

    <method>
      <name>cc</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>cc</code> method adds one or several address to the
      <em>copy list</em>. The address format must conform to
      RFC822. Multiple address are coma separated. Multiple call to
      this method is possible.
      </p>
    </method>

    <method>
      <name>bcc</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>bcc</code> method adds one or several address to the
      <em>blind copy list</em>. The address format must conform to
      RFC822. Multiple address are coma separated. Multiple call to this
      method is possible. The <em>blind copy list</em> is not included in
      the message header.
      </p>
    </method>

    <method>
      <name>add</name>
      <retn>none</retn>
      <args>String ...</args>
      <p>
      The <code>add</code> method adds one or several literals to the
      message buffer. This is the normal way to fill a message buffer
      by string line.
      </p>
    </method>

    <method>
      <name>addln</name>
      <retn>none</retn>
      <args>String ...</args>
      <p>
      The <code>addln</code> method adds one or several literals to
      the message buffer. A newline character is added at the end of
      the line. This is a similar way to fill a message buffer by
      string line.
      </p>
    </method>

    <method>
      <name>send</name>
      <retn>none</retn>
      <args>none</args>
      <p>
      The <code>send</code> method request a message delivery by
      contacting the MTA. Once the MTA has been contacted, the message
      header and the message body is transferred. The MTA is
      responsible to deliver the message to the appropriate
      recipients.
      </p>
    </method>

    <method>
      <name>subject</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>subject</code> method sets the message subject string
      line.
      </p>
    </method>

    <method>
      <name>set-mta-address</name>
      <retn>none</retn>
      <args>String</args>
      <p>
      The <code>set-mta-address</code> method sets the MTA IP address
      that the class needs to contact for mail request. The address
      can be an fully qualified host name or an IP number.
      </p>
    </method>

    <method>
      <name>get-mta-address</name>
      <retn>String</retn>
      <args>none</args>
      <p>
      The <code>get-mta-address</code> method returns the current MTA
      IP address for this mail object.
      </p>
    </method>

    <method>
      <name>set-mta-port</name>
      <retn>none</retn>
      <args>Integer</args>
      <p>
      The <code>set-mta-port</code> method set the current MTA IP port
      number for this mail object. With the MTA IP address, the MTA to
      contact for mail request is uniquely defined. The default port
      value is 25.
      </p>
    </method>

    <method>
      <name>get-mta-port</name>
      <retn>Integer</retn>
      <args>none</args>
      <p>
      The <code>get-mta-port</code> method returns the current MTA IP
      port number for this mail object. The default port value is 25.
      </p>
    </method>
  </object>
</appendix>
