contrib/sendmail/libmilter/docs/smfi_register.html

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