diff options
author | Sergey Poznyakoff <gray@gnu.org.ua> | 2007-04-27 20:45:53 +0000 |
---|---|---|
committer | Sergey Poznyakoff <gray@gnu.org.ua> | 2007-04-27 20:45:53 +0000 |
commit | f1133249d78b4de8a1897f256dba5fabb09646f3 (patch) | |
tree | 0765ea6be492498188be4af0432b0fa8fa54f0b2 /doc | |
parent | 4d3f1f3b87ccb7b42c98b804d86d26504b2fc383 (diff) | |
download | mailfromd-f1133249d78b4de8a1897f256dba5fabb09646f3.tar.gz mailfromd-f1133249d78b4de8a1897f256dba5fabb09646f3.tar.bz2 |
Implement begin/end statements. Allow to disable/enable caching
git-svn-id: file:///svnroot/mailfromd/trunk@1387 7a8a7f39-df28-0410-adc6-e0d955640f24
Diffstat (limited to 'doc')
-rw-r--r-- | doc/mailfromd.texi | 145 |
1 files changed, 138 insertions, 7 deletions
diff --git a/doc/mailfromd.texi b/doc/mailfromd.texi index 6ba94777..f65d4615 100644 --- a/doc/mailfromd.texi +++ b/doc/mailfromd.texi @@ -157,7 +157,8 @@ Mail Filtering Language * Constants:: * Variables:: * Back references:: -* Handlers:: +* Handlers:: +* begin/end:: * Functions:: Functions. * Expressions:: Expressions. * Statements:: @@ -1082,14 +1083,27 @@ be supplied its own handling procedure. A missing procedure implies @cindex milter state handler, described @cindex handler, described +@cindex connect, handler +@cindex helo, handler +@cindex envfrom, handler +@cindex envrcpt, handler +@cindex header, handler +@cindex eoh, handler +@cindex body, handler +@cindex eom, handler +@cindex begin, special handler +@cindex end, special handler @anchor{handler names} A filter script can define up to eight @dfn{milter state handlers}, called after the names of milter states: @samp{connect}, @samp{helo}, @samp{envfrom}, @samp{envrcpt}, @samp{header}, @samp{eoh}, -@samp{body}, and @samp{eom}. The diagram below shows the control flow -when processing an @acronym{SMTP} transaction. Lines marked with -@code{C:} show @acronym{SMTP} commands issued by the remote machine -(the @dfn{client}), those marked with @samp{@result{}} show called handlers +@samp{body}, and @samp{eom}. Two special handlers are available for +initialization and cleran-up purposes: @samp{begin} is called before +the processing starts, and @samp{end} is called after it is finished. +The diagram below shows the control flow when processing an +@acronym{SMTP} transaction. Lines marked with @code{C:} show +@acronym{SMTP} commands issued by the remote machine (the +@dfn{client}), those marked with @samp{@result{}} show called handlers with their arguments. An @r{[R]} appearing at the right end of a line indicates that this part of the transaction can be repeated any number of times: @@ -1098,6 +1112,7 @@ of times: @caption{Mailfromd Control Flow} @smallexample @group +@result{} begin @result{} connect(@var{hostname}, @var{family}, @var{port}, @samp{IP address}) C: HELO @var{domain} helo(@var{domain}) @@ -1124,7 +1139,8 @@ do C: . @result{} eom - done + done +@result{} end @end group @end smallexample @end float @@ -2938,7 +2954,8 @@ amount of white-space characters (i.e. spaces, tabulations or newlines). * Constants:: * Variables:: * Back references:: -* Handlers:: +* Handlers:: +* begin/end:: * Functions:: Functions. * Expressions:: Expressions. * Statements:: @@ -4526,6 +4543,119 @@ For your reference, the following table shows each handler with its arguments: @end multitable @end float +@node begin/end +@section The @samp{begin} and @samp{end} special handlers +@cindex begin, special handler +@cindex end, special handler +@cindex startup handler +@cindex handler, startup +@cindex handler, initialization +@cindex cleanup handler +@cindex handler, cleanup + Apart from milter handlers defined previously, @acronym{MFL} +defines two special handlers, called @samp{begin} and @samp{end}, +which supply startup and cleanup instruction for the filter program. + + The @samp{begin} special handler is executed once for each +@acronym{SMTP} session, after the connection has been established but +before the first milter handler has been called. Similarly, an +@samp{end} handler is executed exactly once, after the connection has +been closed. Neither of handlers takes any arguments. + + The two handlers are defined using the following syntax: + +@smallexample +# @r{Begin handler} +begin +do + @dots{} +done + +# @r{End handler} +end +do + @dots{} +done +@end smallexample + +@noindent +where @samp{@dots{}} represent any @acronym{MFL} statements. + + An @acronym{MFL} program may have multiple @samp{begin} and +@samp{end} definitions. They can be intermixed with other +definitions. The compiler combines all @samp{begin} +statements into a single one, in the order they appear in the +sources. Similarly, all @samp{end} blocks are concatenated together. +The resulting @samp{begin} is called once, at the beginning of each +@acronym{SMTP} session, and @samp{end} is called once at its +termination. + + Multiple @samp{begin} and @samp{end} handlers are a useful feature +for writing modules (@pxref{Modules}), because each module can thus +have its own initialization and cleanup blocks. Notice, however, that +in this case the order in which subsequent @samp{begin} and @samp{end} +blocks are executed is not defined. It is only warranted, that all +@samp{begin} blocks are executed at startup and all @samp{end} blocks +are executed at shutdown. It is also warranted that all @samp{begin} +and @samp{end} blocks defined within a compilation unit (i.e. a single +abstract source file, whith all @code{#include} and +@code{#include_once} statements expanded in place) are executed in +order of their appearance in the unit. + +@cindex @samp{begin}, handler restrictions +@cindex @samp{end}, handler restrictions + Due to their special nature, the startup and cleanup blocks impose +certain restrictions on the statements that can be used within them: + +@enumerate 1 +@cindex @code{return} in @samp{begin} +@cindex @samp{begin} and @code{return} +@cindex @code{return} in @samp{end} +@cindex @samp{end} and @code{return} +@item @code{return} cannot be used in @samp{begin} and @samp{end} +handlers. @FIXME{But could it be a useful feature?} + +@cindex @code{accept} in @samp{begin} +@cindex @samp{begin} and @code{accept} +@cindex @code{accept} in @samp{end} +@cindex @samp{end} and @code{accept} +@cindex @code{continue} in @samp{begin} +@cindex @samp{begin} and @code{continue} +@cindex @code{continue} in @samp{end} +@cindex @samp{end} and @code{continue} +@cindex @code{discard} in @samp{begin} +@cindex @samp{begin} and @code{discard} +@cindex @code{discard} in @samp{end} +@cindex @samp{end} and @code{discard} +@cindex @code{reject} in @samp{begin} +@cindex @samp{begin} and @code{reject} +@cindex @code{reject} in @samp{end} +@cindex @samp{end} and @code{reject} +@cindex @code{tempfail} in @samp{begin} +@cindex @samp{begin} and @code{tempfail} +@cindex @code{tempfail} in @samp{end} +@cindex @samp{end} and @code{tempfail} +@item The following Sendmail actions cannot be used in them: +@code{accept}, @code{continue}, @code{discard}, @code{reject}, +@code{tempfail}. + +@cindex @code{add} in @samp{begin} +@cindex @samp{begin} and @code{add} +@cindex @code{add} in @samp{end} +@cindex @samp{end} and @code{add} +@cindex @code{replace} in @samp{begin} +@cindex @samp{begin} and @code{replace} +@cindex @code{replace} in @samp{end} +@cindex @samp{end} and @code{replace} +@cindex @code{delete} in @samp{begin} +@cindex @samp{begin} and @code{delete} +@cindex @code{delete} in @samp{end} +@cindex @samp{end} and @code{delete} +@item Header manipulation actions (@pxref{header manipulation}) can be +used only in @samp{begin} header. +@end enumerate + +@FIXME{Examples of @samp{begin}/@samp{end}} @node Functions @section Functions @@ -7391,6 +7521,7 @@ reject 503 5.0.0 "Need HELO command" @end group @end smallexample +@anchor{header manipulation} @cindex Header manipulation actions Header manipulation actions allow you to add, delete or modify message @acronym{RFC} 2822 headers. |