<?xml version="1.0" encoding="ISO-8859-1"?>

<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://docbook.org/xml/4.1.2/docbookx.dtd">

<article lang="en">
  <articleinfo>
    <title>libmodxslt API</title>
    <author>
      <firstname>Carlo</firstname>
      <surname>Contavalli</surname>
      <affiliation>
        <address><email>ccontavalli at mod-xslt2.com</email></address>
      </affiliation>
    </author>
    <revhistory>
      <revision>
        <revnumber>1.0.0</revnumber>
        <date>2004/08/25</date>
        <revremark>First document revision</revremark>
      </revision>
    </revhistory>

    <abstract>
      <para>
        Purpose of this document is to introduce developers 
	to the libmodxslt API and usage.
      </para>
    </abstract>
  </articleinfo>

  <sect1 id="bef">
    <title>Before starting</title>

    <para>
      This document was written as part of the documentation
      of the <ulink href="http://www.mod-xslt2.com">mod-xslt2</ulink> 
      project to provide help and support to developers.
    </para>

    <para>
      While every effort has been made to ensure that the 
      information is accurate at the time of publication,
      this document may contain errors, omissions, incongruences 
      or wrong technical details. No liability for damages
      is accepted by the Author/Authors, the publishers or
      any other organization or person providing the information,
      arising from any errors or omissions that may appear,
      however caused.
    </para>

    <para>
      In case you find an error, you would like to propose better
      solutions than those discussed in this document or you
      would like to discuss an idea regarding this document
      or its content, we would be glad to hear from you and
      please feel free to contact us by writing to the &lt;dev
      at ml.mod-xslt2.com&gt; mailing list or by directly 
      contacting one of the authors.
    </para>


    <sect2>
      <title>Intended Audience</title>

      <para>
      </para>
    </sect2>

    <sect2>
      <title>Copyright Notice</title>

      <para>
        This document was written by Carlo Contavalli &lt;ccontavalli at masobit.net&gt; 
        and is thus Copyright (C) Carlo Contavalli 2003, 2004.
      </para>
      <para>
        Permission is granted to copy, distribute and/or modify this document
        under the terms of the GNU Free Documentation License, Version 1.1 or
        any later version published by the Free Software Foundation; with no
        Invariant Sections, no Front-Cover Texts and no Back-Cover Texts.
      </para>

      <para>
        Any example of program code available in this document should be
        considered protected by the terms of the GNU General Public License.
      </para>

      <para>
        You should have received a copy of the GNU General Public License
        along with this document; if not, write to the Free Software
        Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
      </para>

      <para>
        Trademarks are owned by their respective owners. 
      </para>
    </sect2>
  </sect1>
<!--
    <sect2>
      <title>load method</title>
      <para>
        <funcsynopsis>  
	  <funcprototype>
  	    <funcdef>static dscm_mstatus_srv_e <function>dscm_mailToMars_load</function></funcdef>
	    <paramdef>dscm_state_t *<parameter>state</parameter></paramdef>
	    <paramdef>void **<parameter>ld</parameter></paramdef>
	  </funcprototype>
	</funcsynopsis>

        <itemizedlist>
	  <listitem><para>
  	    <parameter>state</parameter> contains the state parameter used by many of the 
	    PigeonDeliver API functions.
	  </para></listitem>
	  
	  <listitem><para>
  	    <parameter>ld</parameter> allows the function to return a custom descriptor,
	    the load_data described in the examples in the previous sections. This descriptor
	    is then passed over to all the other Service methods.
	  </para></listitem>
	</itemizedlist>
	In case an error verifies, the function must return an error and cleanup and reset
	all the allocated resources, like if it was never called. It is acceptable for the
	caller to try to call the <function>load</function> method again in case of failure.
      </para>
      <para>
        The <function>load</function> method can assume it will <emphasis>never be</emphasis>
	called with a NULL <parameter>state</parameter> or <parameter>ld</parameter> parameter,
	and should generate an assertion failed error in case it is.
      </para>
      <para>
        The <function>load</function> method should always make use of the <parameter>ld</parameter>
	parameter. If it is left NULL, the caller can assume: that the load method was never called
	and the ld parameter still needs initialization or that there is no need to call other
	Service methods. In the rare case you don't need it, please set it to a non-zero value
	anyway.
      </para>
    </sect2>
    -->


  <sect1 id="intro">
    <title>What is a PigeonDeliver Service?</title>

    <para>
      A PigeonDeliver Service is a module able to
      handle part of the delivery process of a mail.
    </para>

    <para>
      To know more about how the PigeonDeliver 
      handles emails delivery or how Services
      are used by PigeonDeliver, please refer
      to %TODO%.
    </para>

    <para>
      A PigeonDeliver Service is a C written
      library/program conforming to the structure 
      and rules described in the following sections
      of this document providing the described
      methods or callbacks.
    </para>

    <para>
      PigeonDeliver Services are called and 
      used by PigeonDeliver SAPI and PigeonDeliver
      IPC, whose role is to provide a layer of 
      abstraction over a particular mail server or 
      technology for mail delivery.
    </para>

    <para>
      All PigeonDeliver SAPI and IPC must
      and do behave as described in the following 
      few sections, where they will simply be referred 
      as ``callers'' of the PigeonDeliver Service.
    </para>

    <para>
      To know more about how to port PigeonDeliver
      to different mail servers or on how to write
      PigeonDeliver SAPI or IPC libraries, please
      refer to %TODO%.
    </para>
  </sect1>

</article>

