##
##  lmtp.pod: LMTP library (Unix manual page)
##
##  Copyright (c) 2001 The OSSP Project (http://www.ossp.org/)
##  Copyright (c) 2001 Cable & Wireless Deutschland (http://www.cw.com/de/)
##
##  This file is part of OSSP lmtp2nntp, an LMTP speaking local
##  mailer which forwards mails as Usenet news articles via NNTP.
##  It can be found at http://www.ossp.com/pkg/lmtp2nntp/.
##
##  Permission to use, copy, modify, and distribute this software for
##  any purpose with or without fee is hereby granted, provided that
##  the above copyright notice and this permission notice appear in all
##  copies.
##
##  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
##  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
##  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
##  IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
##  CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
##  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
##  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
##  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
##  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
##  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
##  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
##  SUCH DAMAGE.
##

=pod

=head1 NAME

B<lmtp> - Local Mail Transfer Protocol (LMTP) Library

=head1 SYNOPSIS

=over 4

=item Headers:

B<lmtp.h>.

=item Types:

B<lmtp_t>,
B<lmtp_io_t>,
B<lmtp_req_t>,
B<lmtp_res_t>,
B<lmtp_rc_t>,
B<lmtp_cb_t>.

=item Functions:

B<lmtp_create>,  
B<lmtp_destroy>, 
B<lmtp_readline>,
B<lmtp_readmsg>, 
B<lmtp_request>, 
B<lmtp_response>,
B<lmtp_error>,   
B<lmtp_register>,
B<lmtp_loop>.    

=item Return Codes:

B<LMTP_OK>,
B<LMTP_EOF>,
B<LMTP_ERR_SYSTEM>,
B<LMTP_ERR_MEM>,
B<LMTP_ERR_OVERFLOW>,
B<LMTP_ERR_ARG>,
B<LMTP_ERR_UNKNOWN>.

=back

=head1 DESCRIPTION

This library provides a generic framework for implementing the Local Mail
Transport Protocol (LMTP) in a server application.

The following data types are declared:

=over 4

=item B<lmtp_t>

This is the opaque data type which forms the LMTP session handle.
It is passed through every API function as its context.

=item B<lmtp_io_t>

This is a simple I/O structure which can be passed to ltmp_create(3) in
order override the underlying I/O routines used by the LMTP library.
It contains the following two attributes which match the prototype of
read(2) and write(2).

 ssize_t (*read)(int, void *, size_t);
 ssize_t (*write)(int, const void *, size_t);

=item B<lmtp_req_t>

This is a simple Request structure.
It contains the following two attributes:

 char *verb; /* LMTP request verb */
 char *msg;  /* LMTP request message (whole line) */

=item B<lmtp_res_t>

...

 char *statuscode; /* digit digit digit NUL */
 char *dsncode;    /* digit dot digit dot digit NUL */
 char *statusmsg;  /* message with >=0*NLs, not terminating with NL. NUL */

=item B<lmtp_rc_t>

...

 LMTP_OK
 LMTP_EOF           /* eof */
 LMTP_ERR_SYSTEM    /* see errno */
 LMTP_ERR_MEM       /* dynamic memory allocation failed */
 LMTP_ERR_OVERFLOW  /* static allocated memory exhausted */
 LMTP_ERR_ARG       /* invalid arg was passed to function */
 LMTP_ERR_UNKNOWN   /* guru meditation */

=item B<lmtp_cb_t>

...

lmtp_rc_t (*B<lmtp_cb_t>)(lmtp_t *I<lmtp>, lmtp_io_t *I<io>, lmtp_req_t
*I<req>, void *I<ctx>);

=back

The following API functions are provided:

=item lmtp_t *B<lmtp_create>(int I<rfd>, int I<wfd>, lmtp_io_t *I<io>);

...

=item void B<lmtp_destroy>(lmtp_t *I<lmtp>);

...

=item lmtp_rc_t B<lmtp_readline>(lmtp_t *I<lmtp>, char *I<buf>, size_t I<buflen>);

...

=item lmtp_rc_t B<lmtp_readmsg>(lmtp_t *I<lmtp>, char **I<buf>, size_t I<maxlen>);

...

=item lmtp_rc_t B<lmtp_request>(lmtp_t *I<lmtp>, lmtp_req_t *I<req>);

...

=item lmtp_rc_t B<lmtp_response>(lmtp_t *I<lmtp>, lmtp_res_t *I<res>);

...

=item char *B<lmtp_error>(lmtp_t *I<lmtp>, lmtp_rc_t I<rc>);

...

=item lmtp_rc_t B<lmtp_register>(lmtp_t *I<lmtp>, char *I<verb>, lmtp_cb_t I<cb>, void *I<ctx>, lmtp_cb_t *I<oldcb>, void **I<oldctx>);

...

=item lmtp_rc_t B<lmtp_loop>(lmtp_t *I<lmtp>);

...

=back

=head1 EXAMPLE

...

=head1 STANDARDS

RFC 2033: Local Mail Transfer Protocol (SMTP)

RFC 821, STD 90: Simple Mail Transfer Protocol (SMTP)

RFC 1891: Delivery Status Notification (DSN)

RFC 2920: SMTP Service Extension for Command Pipelining

=head1 AUTHORS

 Thomas Lotterer
 thomas.lotterer@cw.com
 Cable & Wireless Deutschland GmbH
 
 Ralf S. Engelschall
 ralf.engelschall@cw.com
 Cable & Wireless Deutschland GmbH

=cut