contrib/sendmail-8.14/libmilter/docs/smfi_register.html

   1 <HTML>
   2 <HEAD><TITLE>smfi_register</TITLE></HEAD>
   3 <BODY>
   4 <!--
   5 $Id: smfi_register.html,v 1.18 2006/12/20 18:37:11 ca Exp $
   6 -->
   7 <H1>smfi_register</H1>
   8
   9 <TABLE border="0" cellspacing=4 cellpadding=4>
  10 <!---------- Synopsis ----------->
  11 <TR><TH valign="top" align=left width=100>SYNOPSIS</TH><TD>
  12 <PRE>
  13 #include &lt;libmilter/mfapi.h&gt;
  14 int smfi_register(
  15         smfiDesc descr
  16 );
  17 </PRE>
  18 Register a set of filter callbacks.
  19 </TD></TR>
  20
  21 <!----------- Description ---------->
  22 <TR><TH valign="top" align=left>DESCRIPTION</TH><TD>
  23 <TABLE border="1" cellspacing=1 cellpadding=1>
  24 <TR align="left" valign=top>
  25 <TH width="80">Called When</TH>
  26 <TD>smfi_register must be called before smfi_main</TD>
  27 </TR>
  28 <TR align="left" valign=top>
  29 <TH width="80">Effects</TH>
  30 <TD>smfi_register creates a filter using the information given in the
  31 smfiDesc argument.
  32 Multiple (successful) calls to smfi_register within a
  33 single process are not allowed,
  34 i.e., only one filter can be successfully registered.
  35 Note, however, that the library may not check whether this restriction
  36 is obeyed.
  37 </TD>
  38 </TR>
  39 </TABLE>
  40
  41 <!----------- Arguments ---------->
  42 <TR><TH valign="top" align=left>ARGUMENTS</TH><TD>
  43     <TABLE border="1" cellspacing=0>
  44     <TR bgcolor="#dddddd"><TH>Argument</TH><TH>Description</TH></TR>
  45     <TR valign="top"><TD>descr</TD>
  46         <TD>
  47 A filter descriptor of type smfiDesc describing the filter's functions.
  48 <A NAME="smfiDesc">The structure</A> has the following members:
  49 <PRE>
  50 struct smfiDesc
  51 {
  52         char            *xxfi_name;     /* filter name */
  53         int             xxfi_version;   /* version code -- do not change */
  54         unsigned long   xxfi_flags;     /* <A href="#flags">flags</A> */
  55
  56         /* connection info filter */
  57         sfsistat        (*<A href="xxfi_connect.html">xxfi_connect</A>)(SMFICTX *, char *, _SOCK_ADDR *);
  58         /* SMTP HELO command filter */
  59         sfsistat        (*<A href="xxfi_helo.html">xxfi_helo</A>)(SMFICTX *, char *);
  60         /* envelope sender filter */
  61         sfsistat        (*<A href="xxfi_envfrom.html">xxfi_envfrom</A>)(SMFICTX *, char **);
  62         /* envelope recipient filter */
  63         sfsistat        (*<A href="xxfi_envrcpt.html">xxfi_envrcpt</A>)(SMFICTX *, char **);
  64         /* header filter */
  65         sfsistat        (*<A href="xxfi_header.html">xxfi_header</A>)(SMFICTX *, char *, char *);
  66         /* end of header */
  67         sfsistat        (*<A href="xxfi_eoh.html">xxfi_eoh</A>)(SMFICTX *);
  68         /* body block */
  69         sfsistat        (*<A href="xxfi_body.html">xxfi_body</A>)(SMFICTX *, unsigned char *, size_t);
  70         /* end of message */
  71         sfsistat        (*<A href="xxfi_eom.html">xxfi_eom</A>)(SMFICTX *);
  72         /* message aborted */
  73         sfsistat        (*<A href="xxfi_abort.html">xxfi_abort</A>)(SMFICTX *);
  74         /* connection cleanup */
  75         sfsistat        (*<A href="xxfi_close.html">xxfi_close</A>)(SMFICTX *);
  76
  77         /* any unrecognized or unimplemented command filter */
  78         sfsistat        (*xxfi_unknown)(SMFICTX *, const char *);
  79
  80         /* SMTP DATA command filter */
  81         sfsistat        (*xxfi_data)(SMFICTX *);
  82
  83         /* negotiation callback */
  84         sfsistat (*<A HREF="xxfi_negotiate.html">xxfi_negotiate</A>)(SMFICTX *,
  85                 unsigned long, unsigned long, unsigned long, unsigned long,
  86                 unsigned long *, unsigned long *, unsigned long *, unsigned long *);
  87 };
  88 </PRE>
  89
  90 A NULL value for any callback function indicates that the filter
  91 does not wish to process the given type of information,
  92 simply returning SMFIS_CONTINUE.
  93         </TD></TR>
  94     </TABLE>
  95 </TD></TR>
  96
  97 <!----------- Return values ---------->
  98 <TR>
  99 <TH valign="top" align=left>RETURN VALUES</TH>
 100
 101 <TD>
 102 smfi_register may return MI_FAILURE for any of the following reasons:
 103 <UL>
 104 <LI>memory allocation failed.
 105 <LI>incompatible version or illegal flags value.
 106 </UL>
 107
 108 </TD>
 109 </TR>
 110
 111 <!----------- Notes ---------->
 112 <TR align="left" valign=top>
 113 <TH>NOTES</TH>
 114 <TD>
 115
 116 <A NAME="flags">The xxfi_flags</A>
 117 field should contain the bitwise OR of zero or more of
 118 the following values, describing the actions the filter may take:
 119 <TABLE BORDER CELLPADDING="1" cellspacing=1>
 120 <TR valign="top" bgcolor="#dddddd"><TH align="left">Flag</TH><TH align="center">Description</TH></TR>
 121   <TR align="left" valign=top>
 122     <TD>
 123         SMFIF_ADDHDRS
 124     </TD>
 125     <TD>
 126         This filter may <A HREF="smfi_addheader.html">add headers</A>.
 127     </TD>
 128   </TR>
 129   <TR align="left" valign=top>
 130     <TD>
 131         SMFIF_CHGHDRS
 132     </TD>
 133     <TD>
 134         This filter may
 135         <A HREF="smfi_chgheader.html">change and/or delete headers</A>.
 136     </TD>
 137   </TR>
 138   <TR align="left" valign=top>
 139     <TD VALIGN="TOP">
 140         SMFIF_CHGBODY
 141     </TD>
 142     <TD>
 143         This filter may
 144         <A HREF="smfi_replacebody.html">replace the body</A> during filtering.
 145         This may have significant performance impact
 146         if other filters do body filtering after this filter.
 147     </TD>
 148   </TR>
 149   <TR>
 150     <TD VALIGN="TOP">
 151         SMFIF_ADDRCPT
 152     </TD>
 153     <TD>
 154         This filter may
 155         <A HREF="smfi_addrcpt.html">add recipients</A>
 156         to the message.
 157     </TD>
 158   </TR>
 159   <TR>
 160     <TD VALIGN="TOP">
 161         SMFIF_ADDRCPT_PAR
 162     </TD>
 163     <TD>
 164         This filter may
 165         <A HREF="smfi_addrcpt_par.html">add recipients including ESMTP args</A>.
 166     </TD>
 167   </TR>
 168   <TR>
 169     <TD VALIGN="TOP">
 170         SMFIF_DELRCPT
 171     </TD>
 172     <TD>
 173         This filter may
 174         <A HREF="smfi_delrcpt.html">remove recipients</A> from the message.
 175     </TD>
 176   </TR>
 177   <TR>
 178     <TD VALIGN="TOP">
 179         SMFIF_QUARANTINE
 180     </TD>
 181     <TD>
 182         This filter may
 183         <A HREF="smfi_quarantine.html">quarantine</A> a message.
 184     </TD>
 185   </TR>
 186
 187   <TR>
 188     <TD VALIGN="TOP">
 189         SMFIF_CHGFROM
 190     </TD>
 191     <TD>
 192         This filter may
 193         <A HREF="smfi_chgfrom.html">change the envelope sender</A> (MAIL).
 194     </TD>
 195   </TR>
 196
 197   <TR>
 198     <TD VALIGN="TOP">
 199         SMFIF_SETSYMLIST
 200     </TD>
 201     <TD>
 202         This filter can
 203         <A HREF="smfi_setsymlist.html">send a set of symbols (macros)</A>
 204         that it wants.
 205     </TD>
 206   </TR>
 207
 208 </TABLE>
 209
 210 </TD>
 211 </TR>
 212
 213 </TABLE>
 214
 215 <HR size="1">
 216 <FONT size="-1">
 217 Copyright (c) 2000-2001, 2003, 2006 Sendmail, Inc. and its suppliers.
 218 All rights reserved.
 219 <BR>
 220 By using this file, you agree to the terms and conditions set
 221 forth in the LICENSE.
 222 </FONT>
 223 </BODY>
 224 </HTML>