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

   1 <html>
   2 <head><title>smfi_register</title></head>
   3 <body>
   4 <!--
   5 $Id: smfi_register.html,v 1.11 2003/05/26 04:10:52 gshapiro 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=150>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.  Multiple calls to smfi_register within a
  32 single process are not allowed.</td>
  33 </tr>
  34 </table>
  35
  36 <!----------- Arguments ---------->
  37 <tr><th valign="top" align=left>ARGUMENTS</th><td>
  38     <table border="1" cellspacing=0>
  39     <tr bgcolor="#dddddd"><th>Argument</th><th>Description</th></tr>
  40     <tr valign="top"><td>descr</td>
  41         <td>
  42 A filter descriptor of type smfiDesc describing the filter's
  43 functions.  The structure has the following members:
  44 <pre>
  45 struct smfiDesc
  46 {
  47         char            *xxfi_name;     /* filter name */
  48         int             xxfi_version;   /* version code -- do not change */
  49         unsigned long   xxfi_flags;     /* <a href="#flags">flags</a> */
  50
  51         /* connection info filter */
  52         sfsistat        (*<a href="xxfi_connect.html">xxfi_connect</a>)(SMFICTX *, char *, _SOCK_ADDR *);
  53         /* SMTP HELO command filter */
  54         sfsistat        (*<a href="xxfi_helo.html">xxfi_helo</a>)(SMFICTX *, char *);
  55         /* envelope sender filter */
  56         sfsistat        (*<a href="xxfi_envfrom.html">xxfi_envfrom</a>)(SMFICTX *, char **);
  57         /* envelope recipient filter */
  58         sfsistat        (*<a href="xxfi_envrcpt.html">xxfi_envrcpt</a>)(SMFICTX *, char **);
  59         /* header filter */
  60         sfsistat        (*<a href="xxfi_header.html">xxfi_header</a>)(SMFICTX *, char *, char *);
  61         /* end of header */
  62         sfsistat        (*<a href="xxfi_eoh.html">xxfi_eoh</a>)(SMFICTX *);
  63         /* body block */
  64         sfsistat        (*<a href="xxfi_body.html">xxfi_body</a>)(SMFICTX *, unsigned char *, size_t);
  65         /* end of message */
  66         sfsistat        (*<a href="xxfi_eom.html">xxfi_eom</a>)(SMFICTX *);
  67         /* message aborted */
  68         sfsistat        (*<a href="xxfi_abort.html">xxfi_abort</a>)(SMFICTX *);
  69         /* connection cleanup */
  70         sfsistat        (*<a href="xxfi_close.html">xxfi_close</a>)(SMFICTX *);
  71 };
  72 </pre>
  73
  74 A NULL value for any callback function indicates that the filter does
  75 not wish to process the given type of information, simply returning
  76 SMFIS_CONTINUE.
  77         </td></tr>
  78     </table>
  79 </td></tr>
  80
  81 <!----------- Return values ---------->
  82 <tr>
  83 <th valign="top" align=left>RETURN VALUES</th>
  84
  85 <td>
  86 smfi_register may return MI_FAILURE for any of the following reasons:
  87 <ul>
  88 <li>memory allocation failed.
  89 <li>incompatible version or illegal flags value.
  90 </ul>
  91
  92 </td>
  93 </tr>
  94
  95 <!----------- Notes ---------->
  96 <tr align="left" valign=top>
  97 <th>NOTES</th>
  98 <td>
  99
 100 <a name="flags"></A>
 101 The xxfi_flags field should contain the bitwise OR of zero or more of
 102 the following values, describing the actions the filter may take:
 103 <TABLE BORDER CELLPADDING="1" cellspacing=1>
 104 <tr valign="top" bgcolor="#dddddd"><th align="left">Flag</th><th align="center">Description</th></tr>
 105   <TR align="left" valign=top>
 106     <TD>
 107         SMFIF_ADDHDRS
 108     </TD>
 109     <TD>
 110         This filter may add headers.
 111     </TD>
 112   </TR>
 113   <TR align="left" valign=top>
 114     <TD>
 115         SMFIF_CHGHDRS
 116     </TD>
 117     <TD>
 118         This filter may change and/or delete headers.
 119     </TD>
 120   </TR>
 121   <TR align="left" valign=top>
 122     <TD VALIGN="TOP">
 123         SMFIF_CHGBODY
 124     </TD>
 125     <TD>
 126         This filter may replace the body during filtering.
 127         This may have significant performance impact
 128         if other filters do body filtering after this filter.
 129     </TD>
 130   </TR>
 131   <TR>
 132     <TD VALIGN="TOP">
 133         SMFIF_ADDRCPT
 134     </TD>
 135     <TD>
 136         This filter may add recipients to the message.
 137     </TD>
 138   </TR>
 139   <TR>
 140     <TD VALIGN="TOP">
 141         SMFIF_DELRCPT
 142     </TD>
 143     <TD>
 144         This filter may remove recipients from the message.
 145     </TD>
 146   </TR>
 147 </TABLE>
 148
 149 </td>
 150 </tr>
 151
 152 </table>
 153
 154 <hr size="1">
 155 <font size="-1">
 156 Copyright (c) 2000-2001, 2003 Sendmail, Inc. and its suppliers.
 157 All rights reserved.
 158 <br>
 159 By using this file, you agree to the terms and conditions set
 160 forth in the LICENSE.
 161 </font>
 162 </body>
 163 </html>