##
##  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.org/pkg/lmtp2nntp/.
##
##  This program is free software; you can redistribute it and/or
##  modify it under the terms of the GNU General Public  License
##  as published by the Free Software Foundation; either version
##  2.0 of the License, or (at your option) any later version.
##
##  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. See the GNU
##  General Public License for more details.
##
##  You should have received a copy of the GNU General Public License
##  along with this file; if not, write to the Free Software
##  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
##  USA, or contact the OSSP project <ossp@ossp.org>.
##
##  lmtp.pod: Local Mail Transfer Protocol (LMTP) server library (manual page)
##

=pod

=head1 NAME

B<lmtp> - Local Mail Transfer Protocol (LMTP) Server 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