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 <libmilter/mfapi.h> 14int smfi_register( 15 smfiDesc descr 16); 17</PRE> 18Register 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 31smfiDesc argument. 32Multiple (successful) calls to smfi_register within a 33single process are not allowed, 34i.e., only one filter can be successfully registered. 35Note, however, that the library may not check whether this restriction 36is 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> 47A filter descriptor of type smfiDesc describing the filter's functions. 48<A NAME="smfiDesc">The structure</A> has the following members: 49<PRE> 50struct 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 90A NULL value for any callback function indicates that the filter 91does not wish to process the given type of information, 92simply 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> 102smfi_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> 117field should contain the bitwise OR of zero or more of 118the 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"> 217Copyright (c) 2000-2001, 2003, 2006 Sendmail, Inc. and its suppliers. 218All rights reserved. 219<BR> 220By using this file, you agree to the terms and conditions set 221forth in the LICENSE. 222</FONT> 223</BODY> 224</HTML> 225