ossp-pkg/lmtp2nntp/lmtp.pod
##
## 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
