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