contrib/sendmail/libmilter/docs/smfi_register.html

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