diff options
Diffstat (limited to 'contrib/sendmail/libmilter/docs/overview.html')
| -rw-r--r-- | contrib/sendmail/libmilter/docs/overview.html | 215 |
1 files changed, 0 insertions, 215 deletions
diff --git a/contrib/sendmail/libmilter/docs/overview.html b/contrib/sendmail/libmilter/docs/overview.html deleted file mode 100644 index b7e80dfdbed70..0000000000000 --- a/contrib/sendmail/libmilter/docs/overview.html +++ /dev/null @@ -1,215 +0,0 @@ -<HTML> -<HEAD> -<TITLE>Technical Overview</TITLE> -</HEAD> -<BODY> -<!-- -$Id: overview.html,v 1.19 2006/12/21 18:23:47 ca Exp $ ---> - -<H1>Technical Overview</H1> - -<H2>Contents</H2> - -<UL> - <LI><A HREF="#Initialization">Initialization</A> - <LI><A HREF="#ControlFlow">Control Flow</A> - <LI><A HREF="#Multithreading">Multithreading</A> - <LI><A HREF="#ResourceManagement">Resource Management</A> - <LI><A HREF="#SignalHandling">Signal Handling</A> -</UL> - -<H2><A NAME="Initialization">Initialization</A></H2> - -In addition to its own initialization, -libmilter expects a filter to initialize several parameters -before calling <A HREF="smfi_main.html">smfi_main</A>: -<UL> - <LI>The callbacks the filter wishes to be called, and the types of - message modification it intends to perform (required, see - <A HREF="smfi_register.html">smfi_register</A>). - - <LI>The socket address to be used when communicating with the MTA - (required, see <A HREF="smfi_setconn.html">smfi_setconn</A>). - - <LI>The number of seconds to wait for MTA connections before - timing out (optional, see - <A HREF="smfi_settimeout.html">smfi_settimeout</A>). -</UL> -<P> -If the filter fails to initialize libmilter, -or if one or more of the parameters it has passed are invalid, -a subsequent call to smfi_main will fail. - -<H2><A NAME="ControlFlow">Control Flow</A></H2> - -<P> -The following pseudocode describes the filtering process from the -perspective of a set of <CODE>N</CODE> MTA's, -each corresponding to a connection. -Callbacks are shown beside the processing stages in which they are invoked; -if no callbacks are defined for a particular stage, -that stage may be bypassed. -Though it is not shown, -processing may be aborted at any time during a message, -in which case the -<A HREF="xxfi_abort.html">xxfi_abort</A> callback is invoked and control -returns to <CODE>MESSAGE</CODE>. -<P> -<PRE> -For each of N connections -{ - For each filter - process connection/helo (<A HREF="xxfi_connect.html">xxfi_connect</A>, <A HREF="xxfi_helo.html">xxfi_helo</A>) -MESSAGE:For each message in this connection (sequentially) - { - For each filter - process sender (<A HREF="xxfi_envfrom.html">xxfi_envfrom</A>) - For each recipient - { - For each filter - process recipient (<A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A>) - } - For each filter - { - process DATA (<A HREF="xxfi_data.html">xxfi_data</A>) - For each header - process header (<A HREF="xxfi_header.html">xxfi_header</A>) - process end of headers (<A HREF="xxfi_eoh.html">xxfi_eoh</A>) - For each body block - process this body block (<A HREF="xxfi_body.html">xxfi_body</A>) - process end of message (<A HREF="xxfi_eom.html">xxfi_eom</A>) - } - } - For each filter - process end of connection (<A HREF="xxfi_close.html">xxfi_close</A>) -} -</PRE> - -<P>Note: Filters are contacted in order defined in config file.</P> - -<P> -To write a filter, a vendor supplies callbacks to process relevant -parts of a message transaction. -The library then controls all sequencing, threading, -and protocol exchange with the MTA. -<A HREF="#figure-3">Figure 3</A> outlines control flow for a filter -process, showing where different callbacks are invoked. -</P> - -<DIV ALIGN="center"><A NAME="figure-3"></A> -<TABLE border=1 cellspacing=0 cellpadding=2 width="70%"> -<TR bgcolor="#dddddd"><TH>SMTP Commands</TH><TH>Milter Callbacks</TH></TR> -<TR><TD>(open SMTP connection)</TD><TD>xxfi_connect</TD></TR> -<TR><TD>HELO ...</TD><TD>xxfi_helo</TD></TR> -<TR><TD>MAIL From: ...</TD><TD>xxfi_envfrom</TD></TR> -<TR><TD>RCPT To: ...</TD><TD>xxfi_envrcpt</TD></TR> -<TR><TD>[more RCPTs]</TD><TD>[xxfi_envrcpt]</TD></TR> -<TR><TD>DATA</TD><TD>xxfi_data</TD></TR> -<TR><TD>Header: ...</TD><TD>xxfi_header</TD></TR> -<TR><TD>[more headers]</TD><TD>[xxfi_header]</TD></TR> -<TR><TD> </TD><TD>xxfi_eoh</TD></TR> -<TR><TD>body... </TD><TD>xxfi_body</TD></TR> -<TR><TD>[more body...]</TD><TD>[xxfi_body]</TD></TR> -<TR><TD>.</TD><TD>xxfi_eom</TD></TR> -<TR><TD>QUIT</TD><TD>xxfi_close</TD></TR> -<TR><TD>(close SMTP connection)</TD><TD> </TD></TR> -</TABLE> -<B>Figure 3: Milter callbacks related to an SMTP transaction.</B> -</DIV> - -<P> -Note that although only a single message is shown above, multiple -messages may be sent in a single connection. -Note also that a message or connection may be aborted by -either the remote host or the MTA -at any point during the SMTP transaction. -f this occurs during a message (between the MAIL command and the final "."), -the filter's -<A HREF="xxfi_abort.html">xxfi_abort</A> routine will be called. -<A HREF="xxfi_close.html">xxfi_close</A> is called any time the -connection closes. - -<H2><A NAME="Multithreading">Multithreading</A></H2> - -<P> -A single filter process may handle any number of connections -simultaneously. -All filtering callbacks must therefore be reentrant, -and use some appropriate external synchronization methods to access -global data. -Furthermore, since there is not a one-to-one correspondence -between threads and connections -(N connections mapped onto M threads, M <= N), -connection-specific data must be accessed -through the handles provided by the Milter library. -The programmer cannot rely on library-supplied thread-specific data blocks -(e.g., <CODE>pthread_getspecific(3)</CODE>) to store connection-specific data. -See the API documentation for -<A HREF="smfi_setpriv.html">smfi_setpriv</A> and -<A HREF="smfi_getpriv.html">smfi_getpriv</A> for details. - -<H2><A NAME="ResourceManagement">Resource Management</A></H2> - -Since filters are likely to be long-lived, -and to handle many connections, -proper deallocation of per-connection resources is important. -The lifetime of a connection is bracketed by calls to the -callbacks <A HREF="xxfi_connect.html">xxfi_connect</A> and -<A HREF="xxfi_close.html">xxfi_close</A>. -Therefore connection-specific -resources (accessed via <A HREF="smfi_getpriv.html">smfi_getpriv</A> -and <A HREF="smfi_setpriv.html">smfi_setpriv</A>) may be allocated in -<A HREF="xxfi_connect.html">xxfi_connect</A>, -and should be freed in -<A HREF="xxfi_close.html">xxfi_close</A>. -For further information see -the <A HREF="api.html#conn-msg">discussion</A> of message- versus -connection-oriented routines. -In particular, -note that there is only one connection-specific data pointer per connection. -<P> - -Each message is bracketed by calls to -<A HREF="xxfi_envfrom.html">xxfi_envfrom</A> and -<A HREF="xxfi_eom.html">xxfi_eom</A> (or -<A HREF="xxfi_abort.html">xxfi_abort</A>), -implying that message-specific resources can be allocated -and reclaimed in these routines. -Since the messages in a connection are processed sequentially by each filter, -there will be only one active message associated with a given -connection and filter (and connection-private data block). -These resources must still be accessed through -<A HREF="smfi_getpriv.html">smfi_getpriv</A> and -<A HREF="smfi_setpriv.html">smfi_setpriv</A>, -and must be reclaimed in -<A HREF="xxfi_abort.html">xxfi_abort</A>. - -<H2><A NAME="SignalHandling">Signal Handling</A></H2> - -libmilter takes care of signal handling, -the filters are not influenced directly by signals. -There are basically two types of signal handlers: - -<OL> -<LI><TT>Stop</TT>: no new connections from the MTA will be accepted, -but existing connections are allowed to continue. -<LI><TT>Abort</TT>: all filters will be stopped as soon as the next -communication with the MTA happens. -</OL> - -Filters are not terminated asynchronously -(except by signals that can't be caught). -In the case of <TT>Abort</TT> the -<A HREF="xxfi_abort.html">xxfi_abort</A> callback is invoked. - -<HR size="1"> -<FONT size="-1"> -Copyright (c) 2000, 2001, 2003, 2006 Sendmail, Inc. and its suppliers. -All rights reserved. -<BR> -By using this file, you agree to the terms and conditions set -forth in the LICENSE. -</FONT> -</BODY> -</HTML> |