1<HTML> 2<HEAD><TITLE>Milter API</TITLE></HEAD> 3<BODY> 4<!-- 5$Id: api.html,v 1.37 2009/05/19 00:40:52 ca Exp $ 6--> 7<H1>Milter API</H1> 8 9<H2>Contents</H2> 10<UL> 11 <LI><A HREF="#LibraryControlFunctions">Library Control Functions</A> 12 <LI><A HREF="#DataAccessFunctions">Data Access Functions</A> 13 <LI><A HREF="#MessageModificationFunctions">Message Modification Functions</A> 14 <LI><A HREF="#Callbacks">Callbacks</A> 15 <LI><A HREF="#Miscellaneous">Miscellaneous</A> 16</UL> 17 18<H2><A NAME="LibraryControlFunctions">Library Control Functions</A></H2> 19 20Before handing control to libmilter (by calling 21<A HREF="smfi_main.html">smfi_main</A>), a filter may call the following 22functions to set libmilter parameters. 23In particular, the filter must call 24<A HREF="smfi_register.html">smfi_register</A> to register its callbacks. 25Each function will return either MI_SUCCESS or MI_FAILURE to 26indicate the status of the operation. 27 28<P> 29None of these functions communicate with the MTA. All alter the 30library's state, some of which is communicated to the MTA inside 31<A HREF="smfi_main.html">smfi_main</A>. 32 33<P> 34<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 35 36<TR><TD><A HREF="smfi_opensocket.html">smfi_opensocket</A></TD><TD>Try to create the interface socket.</TD></TR> 37 38<TR><TD><A HREF="smfi_register.html">smfi_register</A></TD><TD>Register a filter.</TD></TR> 39 40<TR><TD><A HREF="smfi_setconn.html">smfi_setconn</A></TD><TD>Specify socket to use.</TD></TR> 41 42<TR><TD><A HREF="smfi_settimeout.html">smfi_settimeout</A></TD><TD>Set timeout.</TD></TR> 43 44<TR><TD><A HREF="smfi_setbacklog.html">smfi_setbacklog</A></TD><TD>Define the incoming <CODE>listen(2)</CODE> queue size.</TD></TR> 45 46<TR><TD><A HREF="smfi_setdbg.html">smfi_setdbg</A></TD><TD>Set the milter library debugging (tracing) level.</TD></TR> 47 48<TR><TD><A HREF="smfi_stop.html">smfi_stop</A></TD><TD>Cause an orderly shutdown.</TD></TR> 49 50<TR><TD><A HREF="smfi_main.html">smfi_main</A></TD><TD>Hand control to libmilter.</TD></TR> 51 52</TABLE> 53 54<H2><A NAME="DataAccessFunctions">Data Access Functions</A></H2> 55 56The following functions may be called from within the filter-defined callbacks 57to access information about the current connection or message. 58<P> 59<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR bgcolor="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 60<TR><TD><A HREF="smfi_getsymval.html">smfi_getsymval</A></TD><TD>Return the value 61of a symbol.</TD></TR> 62 63<TR><TD><A HREF="smfi_getpriv.html">smfi_getpriv</A></TD><TD>Get the private data 64pointer.</TD></TR> 65 66<TR><TD><A HREF="smfi_setpriv.html">smfi_setpriv</A></TD><TD>Set the private data 67pointer.</TD></TR> 68 69<TR><TD><A HREF="smfi_setreply.html">smfi_setreply</A></TD><TD>Set the specific 70reply code to be used.</TD></TR> 71 72<TR><TD><A HREF="smfi_setmlreply.html">smfi_setmlreply</A></TD><TD>Set the 73specific multi-line reply to be used.</TD></TR> 74 75</TABLE> 76 77<H2><A NAME="MessageModificationFunctions">Message Modification Functions</A></H2> 78 79The following functions change a message's contents and attributes. 80<EM>They may only be called in <A HREF="xxfi_eom.html">xxfi_eom</A></EM>. 81All of these functions may invoke additional communication with the MTA. 82They will return either MI_SUCCESS or MI_FAILURE to indicate the status of 83the operation. Message data (senders, recipients, headers, body chunks) 84passed to these functions via parameters is copied and does not need to be 85preserved (i.e., allocated memory can be freed). 86 87<P> 88A filter must have set the appropriate flag (listed below) in the 89description passed to <A HREF="smfi_register.html">smfi_register</A> 90to call any message modification function. Failure to do so will 91cause the MTA to treat a call to the function as a failure of the 92filter, terminating its connection. 93 94<P> 95Note that the status returned indicates only whether or not the 96filter's message was successfully sent to the MTA, not whether or not 97the MTA performed the requested operation. For example, 98<A HREF="smfi_addheader.html">smfi_addheader</A>, when called with an 99illegal header name, will return MI_SUCCESS even though the MTA may 100later refuse to add the illegal header. 101<P> 102<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH><TH>SMFIF_* flag</TR> 103<TR><TD><A HREF="smfi_addheader.html">smfi_addheader</A></TD><TD>Add a header to 104the message.</TD><TD>SMFIF_ADDHDRS</TD></TR> 105 106<TR><TD><A HREF="smfi_chgheader.html">smfi_chgheader</A></TD><TD>Change or delete a header.</TD><TD>SMFIF_CHGHDRS</TD></TR> 107 108<TR><TD><A HREF="smfi_insheader.html">smfi_insheader</A></TD><TD>Insert a 109header into the message.</TD><TD>SMFIF_ADDHDRS</TD></TR> 110 111<TR><TD><A HREF="smfi_chgfrom.html">smfi_chgfrom</A></TD><TD>Change the 112envelope sender address.</TD><TD>SMFIF_CHGFROM</TD></TR> 113 114<TR><TD><A HREF="smfi_addrcpt.html">smfi_addrcpt</A></TD><TD>Add a recipient to 115the envelope.</TD><TD>SMFIF_ADDRCPT</TD></TR> 116 117<TR><TD><A HREF="smfi_addrcpt_par.html">smfi_addrcpt_par</A></TD><TD>Add 118a recipient including ESMTP parameter to the envelope. 119</TD><TD>SMFIF_ADDRCPT_PAR</TD></TR> 120 121<TR><TD><A HREF="smfi_delrcpt.html">smfi_delrcpt</A></TD><TD>Delete a recipient 122from the envelope.</TD><TD>SMFIF_DELRCPT</TD></TR> 123 124<TR><TD><A HREF="smfi_replacebody.html">smfi_replacebody</A></TD><TD>Replace the 125body of the message.</TD><TD>SMFIF_CHGBODY</TD></TR> 126 127</TABLE> 128 129<H2>Other Message Handling Functions</H2> 130 131The following functions provide special case handling instructions for 132milter or the MTA, without altering the content or status of the message. 133<EM>They too may only be called in <A HREF="xxfi_eom.html">xxfi_eom</A></EM>. 134All of these functions may invoke additional communication with the MTA. 135They will return either MI_SUCCESS or MI_FAILURE to indicate the status of 136the operation. 137 138<P> 139Note that the status returned indicates only whether or not the 140filter's message was successfully sent to the MTA, not whether or not 141the MTA performed the requested operation. 142 143<P> 144<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 145<TR><TD><A HREF="smfi_progress.html">smfi_progress</A></TD><TD>Report operation in progress.</TD></TR> 146 147<TR><TD><A HREF="smfi_quarantine.html">smfi_quarantine</A></TD><TD>Quarantine a message.</TD></TR> 148 149</TABLE> 150 151<H2><A NAME="Callbacks">Callbacks</A></H2> 152 153The filter should implement one or more of the following callbacks, 154which are registered via <A HREF="smfi_register.html">smfi_register</A>: 155 156<P> 157<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 158 159<TR><TD><A HREF="xxfi_connect.html">xxfi_connect</A></TD><TD>connection info</TD></TR> 160 161<TR><TD><A HREF="xxfi_helo.html">xxfi_helo</A></TD><TD>SMTP HELO/EHLO command</TD></TR> 162 163<TR><TD><A HREF="xxfi_envfrom.html">xxfi_envfrom</A></TD><TD>envelope sender</TD></TR> 164 165<TR><TD><A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A></TD><TD>envelope recipient</TD></TR> 166 167<TR><TD><A HREF="xxfi_data.html">xxfi_data</A></TD><TD>DATA command</TD></TR> 168 169<TR><TD><A HREF="xxfi_unknown.html">xxfi_unknown</A></TD><TD>Unknown SMTP command</TD></TR> 170 171<TR><TD><A HREF="xxfi_header.html">xxfi_header</A></TD><TD>header</TD></TR> 172 173<TR><TD><A HREF="xxfi_eoh.html">xxfi_eoh</A></TD><TD>end of header</TD></TR> 174 175<TR><TD><A HREF="xxfi_body.html">xxfi_body</A></TD><TD>body block</TD></TR> 176 177<TR><TD><A HREF="xxfi_eom.html">xxfi_eom</A></TD><TD>end of message</TD></TR> 178 179<TR><TD><A HREF="xxfi_abort.html">xxfi_abort</A></TD><TD>message aborted</TD></TR> 180 181<TR><TD><A HREF="xxfi_close.html">xxfi_close</A></TD><TD>connection cleanup</TD></TR> 182 183<TR><TD><A HREF="xxfi_negotiate.html">xxfi_negotiate</A></TD><TD>option negotiattion</TD></TR> 184 185</TABLE> 186 187<P> 188The above callbacks should all return one of the following return values, 189having the indicated meanings. Any return other than one of the below 190values constitutes an error, and will cause sendmail to terminate its 191connection to the offending filter. 192 193<P><A NAME="conn-spec">Milter</A> distinguishes between recipient-, 194message-, and connection-oriented routines. Recipient-oriented 195callbacks may affect the processing of a single message recipient; 196message-oriented callbacks, a single message; connection-oriented 197callbacks, an entire connection (during which multiple messages may be 198delivered to multiple sets of recipients). 199<A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A> is recipient-oriented. 200<A HREF="xxfi_connect.html">xxfi_connect</A>, 201<A HREF="xxfi_helo.html">xxfi_helo</A> and 202<A HREF="xxfi_close.html">xxfi_close</A> are connection-oriented. All 203other callbacks are message-oriented. 204 205<P> 206<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2> 207 <TR BGCOLOR="#dddddd"><TH>Return value</TH><TH>Description</TH></TR> 208 <TR VALIGN="TOP"> 209 <TD>SMFIS_CONTINUE</TD> 210 <TD>Continue processing the current connection, message, or recipient. 211 </TD> 212 </TR> 213 <TR VALIGN="TOP"> 214 <TD>SMFIS_REJECT</TD> 215 <TD>For a connection-oriented routine, reject this connection; call <A HREF="xxfi_close.html">xxfi_close</A>.<BR> 216 For a message-oriented routine (except 217 <A HREF="xxfi_eom.html">xxfi_eom</A> or 218 <A HREF="xxfi_abort.html">xxfi_abort</A>), reject this message.<BR> 219 For a recipient-oriented routine, reject the current recipient (but continue processing the current message). 220 </TD> 221 </TR> 222 <TR valign="top"> 223 <TD>SMFIS_DISCARD</TD> 224 <TD>For a message- or recipient-oriented routine, accept this message, but silently discard it.<BR> 225 SMFIS_DISCARD should not be returned by a connection-oriented routine. 226 </TD> 227 </TR> 228 <TR valign="top"> 229 <TD>SMFIS_ACCEPT</TD> 230 <TD>For a connection-oriented routine, accept this connection without further filter processing; call <A HREF="xxfi_close.html">xxfi_close</A>.<BR> 231 For a message- or recipient-oriented routine, accept this message without further filtering.<BR> 232 </TD> 233 </TR> 234 <TR valign="top"> 235 <TD>SMFIS_TEMPFAIL</TD> 236 <TD>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code. 237 For a message-oriented routine (except <A HREF="xxfi_envfrom.html">xxfi_envfrom</A>), fail for this message. <BR> 238 For a connection-oriented routine, fail for this connection; call <A HREF="xxfi_close.html">xxfi_close</A>. <BR> 239 For a recipient-oriented routine, only fail for the current recipient; continue message processing. 240 </TD> 241 </TR> 242 243 <TR valign="top"> 244 <TD><A NAME="SMFIS_SKIP">SMFIS_SKIP</A></TD> 245 <TD>Skip further callbacks of the same type in this transaction. 246 Currently this return value is only allowed in 247 <A HREF="xxfi_body.html">xxfi_body()</A>. 248 It can be used if a milter has received sufficiently many 249 body chunks to make a decision, but still wants to invoke 250 message modification functions that are only allowed to be called from 251 <A HREF="xxfi_eom.html">xxfi_eom()</A>. 252 Note: the milter <EM>must</EM> 253 <A HREF="xxfi_negotiate.html">negotiate</A> 254 this behavior with the MTA, i.e., it must check whether 255 the protocol action 256 <A HREF="xxfi_negotiate.html#SMFIP_SKIP"><CODE>SMFIP_SKIP</CODE></A> 257 is available and if so, the milter must request it. 258 </TD> 259 </TR> 260 261 <TR valign="top"> 262 <TD><A NAME="SMFIS_NOREPLY">SMFIS_NOREPLY</A></TD> 263 <TD>Do not send a reply back to the MTA. 264 The milter <EM>must</EM> 265 <A HREF="xxfi_negotiate.html">negotiate</A> 266 this behavior with the MTA, i.e., it must check whether 267 the appropriate protocol action 268 <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 269 is available and if so, the milter must request it. 270 If you set the 271 <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 272 protocol action for a callback, that callback <EM>must</EM> 273 always reply with 274 SMFIS_NOREPLY. 275 Using any other reply code is a violation of the API. 276 If in some cases your callback may return another value 277 (e.g., due to some resource shortages), then you 278 <EM>must not</EM> set 279 <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 280 and you must use 281 SMFIS_CONTINUE as the default return code. 282 (Alternatively you can try to delay reporting the problem to 283 a later callback for which 284 <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 285 is not set.) 286 </TD> 287 </TR> 288 289</TABLE> 290 291<H2><A NAME="Miscellaneous">Miscellaneous</A></H2> 292 293<P> 294<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 295 296<TR><TD><A HREF="smfi_version.html">smfi_version</A></TD><TD>libmilter (runtime) version info</TD></TR> 297 298<TR><TD><A HREF="smfi_setsymlist.html">smfi_setsymlist</A></TD><TD> 299Set the list of macros that the milter wants to receive from the MTA 300for a protocol stage. 301</TD></TR> 302 303</TABLE> 304 305<P> 306<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Constant</TH><TH>Description</TH></TR> 307 308<TR><TD><A HREF="smfi_version.html">SMFI_VERSION</A></TD><TD>libmilter (compile time) version info</TD></TR> 309 310</TABLE> 311 312 313<HR SIZE="1"> 314<FONT SIZE="-1"> 315Copyright (c) 2000, 2003, 2006, 2009 Sendmail, Inc. and its suppliers. 316All rights reserved. 317<BR> 318By using this file, you agree to the terms and conditions set 319forth in the LICENSE. 320</FONT> 321</BODY> 322</HTML> 323