api.html revision 244833
1254885Sdumbbell<HTML> 2254885Sdumbbell<HEAD><TITLE>Milter API</TITLE></HEAD> 3254885Sdumbbell<BODY> 4254885Sdumbbell<!-- 5254885Sdumbbell$Id: api.html,v 1.38 2012/03/29 03:18:37 ca Exp $ 6254885Sdumbbell--> 7254885Sdumbbell<H1>Milter API</H1> 8254885Sdumbbell 9254885Sdumbbell<H2>Contents</H2> 10254885Sdumbbell<UL> 11254885Sdumbbell <LI><A HREF="#LibraryControlFunctions">Library Control Functions</A> 12254885Sdumbbell <LI><A HREF="#DataAccessFunctions">Data Access Functions</A> 13254885Sdumbbell <LI><A HREF="#MessageModificationFunctions">Message Modification Functions</A> 14254885Sdumbbell <LI><A HREF="#Callbacks">Callbacks</A> 15254885Sdumbbell <LI><A HREF="#Miscellaneous">Miscellaneous</A> 16254885Sdumbbell</UL> 17254885Sdumbbell 18254885Sdumbbell<H2><A NAME="LibraryControlFunctions">Library Control Functions</A></H2> 19254885Sdumbbell 20254885SdumbbellBefore handing control to libmilter (by calling 21254885Sdumbbell<A HREF="smfi_main.html">smfi_main</A>), a filter may call the following 22254885Sdumbbellfunctions to set libmilter parameters. 23254885SdumbbellIn particular, the filter must call 24254885Sdumbbell<A HREF="smfi_register.html">smfi_register</A> to register its callbacks. 25254885SdumbbellEach function will return either MI_SUCCESS or MI_FAILURE to 26254885Sdumbbellindicate the status of the operation. 27254885Sdumbbell 28254885Sdumbbell<P> 29254885SdumbbellNone of these functions communicate with the MTA. All alter the 30254885Sdumbbelllibrary's state, some of which is communicated to the MTA inside 31254885Sdumbbell<A HREF="smfi_main.html">smfi_main</A>. 32254885Sdumbbell 33254885Sdumbbell<P> 34254885Sdumbbell<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 35254885Sdumbbell 36254885Sdumbbell<TR><TD><A HREF="smfi_opensocket.html">smfi_opensocket</A></TD><TD>Try to create the interface socket.</TD></TR> 37254885Sdumbbell 38254885Sdumbbell<TR><TD><A HREF="smfi_register.html">smfi_register</A></TD><TD>Register a filter.</TD></TR> 39254885Sdumbbell 40254885Sdumbbell<TR><TD><A HREF="smfi_setconn.html">smfi_setconn</A></TD><TD>Specify socket to use.</TD></TR> 41254885Sdumbbell 42254885Sdumbbell<TR><TD><A HREF="smfi_settimeout.html">smfi_settimeout</A></TD><TD>Set timeout.</TD></TR> 43254885Sdumbbell 44254885Sdumbbell<TR><TD><A HREF="smfi_setbacklog.html">smfi_setbacklog</A></TD><TD>Define the incoming <CODE>listen(2)</CODE> queue size.</TD></TR> 45254885Sdumbbell 46254885Sdumbbell<TR><TD><A HREF="smfi_setdbg.html">smfi_setdbg</A></TD><TD>Set the milter library debugging (tracing) level.</TD></TR> 47254885Sdumbbell 48254885Sdumbbell<TR><TD><A HREF="smfi_stop.html">smfi_stop</A></TD><TD>Cause an orderly shutdown.</TD></TR> 49254885Sdumbbell 50254885Sdumbbell<TR><TD><A HREF="smfi_main.html">smfi_main</A></TD><TD>Hand control to libmilter.</TD></TR> 51254885Sdumbbell 52254885Sdumbbell</TABLE> 53254885Sdumbbell 54254885Sdumbbell<H2><A NAME="DataAccessFunctions">Data Access Functions</A></H2> 55254885Sdumbbell 56254885SdumbbellThe following functions may be called from within the filter-defined callbacks 57254885Sdumbbellto access information about the current connection or message. 58254885Sdumbbell<P> 59254885Sdumbbell<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR bgcolor="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 60254885Sdumbbell<TR><TD><A HREF="smfi_getsymval.html">smfi_getsymval</A></TD><TD>Return the value 61254885Sdumbbellof a symbol.</TD></TR> 62254885Sdumbbell 63254885Sdumbbell<TR><TD><A HREF="smfi_getpriv.html">smfi_getpriv</A></TD><TD>Get the private data 64254885Sdumbbellpointer.</TD></TR> 65254885Sdumbbell 66254885Sdumbbell<TR><TD><A HREF="smfi_setpriv.html">smfi_setpriv</A></TD><TD>Set the private data 67254885Sdumbbellpointer.</TD></TR> 68254885Sdumbbell 69254885Sdumbbell<TR><TD><A HREF="smfi_setreply.html">smfi_setreply</A></TD><TD>Set the specific 70254885Sdumbbellreply code to be used.</TD></TR> 71254885Sdumbbell 72254885Sdumbbell<TR><TD><A HREF="smfi_setmlreply.html">smfi_setmlreply</A></TD><TD>Set the 73254885Sdumbbellspecific multi-line reply to be used.</TD></TR> 74254885Sdumbbell 75254885Sdumbbell</TABLE> 76254885Sdumbbell 77254885Sdumbbell<H2><A NAME="MessageModificationFunctions">Message Modification Functions</A></H2> 78254885Sdumbbell 79254885SdumbbellThe following functions change a message's contents and attributes. 80254885Sdumbbell<EM>They may only be called in <A HREF="xxfi_eom.html">xxfi_eom</A></EM>. 81254885SdumbbellAll of these functions may invoke additional communication with the MTA. 82254885SdumbbellThey will return either MI_SUCCESS or MI_FAILURE to indicate the status of 83254885Sdumbbellthe operation. Message data (senders, recipients, headers, body chunks) 84254885Sdumbbellpassed to these functions via parameters is copied and does not need to be 85254885Sdumbbellpreserved (i.e., allocated memory can be freed). 86254885Sdumbbell 87254885Sdumbbell<P> 88254885SdumbbellA filter must have set the appropriate flag (listed below) in the 89254885Sdumbbelldescription passed to <A HREF="smfi_register.html">smfi_register</A> 90254885Sdumbbellto call any message modification function. Failure to do so will 91254885Sdumbbellcause the MTA to treat a call to the function as a failure of the 92254885Sdumbbellfilter, terminating its connection. 93254885Sdumbbell 94254885Sdumbbell<P> 95254885SdumbbellNote that the status returned indicates only whether or not the 96254885Sdumbbellfilter's message was successfully sent to the MTA, not whether or not 97254885Sdumbbellthe MTA performed the requested operation. For example, 98254885Sdumbbell<A HREF="smfi_addheader.html">smfi_addheader</A>, when called with an 99254885Sdumbbellillegal header name, will return MI_SUCCESS even though the MTA may 100254885Sdumbbelllater refuse to add the illegal header. 101254885Sdumbbell<P> 102254885Sdumbbell<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH><TH>SMFIF_* flag</TR> 103254885Sdumbbell<TR><TD><A HREF="smfi_addheader.html">smfi_addheader</A></TD><TD>Add a header to 104254885Sdumbbellthe message.</TD><TD>SMFIF_ADDHDRS</TD></TR> 105254885Sdumbbell 106254885Sdumbbell<TR><TD><A HREF="smfi_chgheader.html">smfi_chgheader</A></TD><TD>Change or delete a header.</TD><TD>SMFIF_CHGHDRS</TD></TR> 107254885Sdumbbell 108254885Sdumbbell<TR><TD><A HREF="smfi_insheader.html">smfi_insheader</A></TD><TD>Insert a 109254885Sdumbbellheader into the message.</TD><TD>SMFIF_ADDHDRS</TD></TR> 110254885Sdumbbell 111254885Sdumbbell<TR><TD><A HREF="smfi_chgfrom.html">smfi_chgfrom</A></TD><TD>Change the 112254885Sdumbbellenvelope sender address.</TD><TD>SMFIF_CHGFROM</TD></TR> 113254885Sdumbbell 114254885Sdumbbell<TR><TD><A HREF="smfi_addrcpt.html">smfi_addrcpt</A></TD><TD>Add a recipient to 115254885Sdumbbellthe envelope.</TD><TD>SMFIF_ADDRCPT</TD></TR> 116254885Sdumbbell 117254885Sdumbbell<TR><TD><A HREF="smfi_addrcpt_par.html">smfi_addrcpt_par</A></TD><TD>Add 118254885Sdumbbella recipient including ESMTP parameter to the envelope. 119254885Sdumbbell</TD><TD>SMFIF_ADDRCPT_PAR</TD></TR> 120254885Sdumbbell 121254885Sdumbbell<TR><TD><A HREF="smfi_delrcpt.html">smfi_delrcpt</A></TD><TD>Delete a recipient 122254885Sdumbbellfrom the envelope.</TD><TD>SMFIF_DELRCPT</TD></TR> 123254885Sdumbbell 124254885Sdumbbell<TR><TD><A HREF="smfi_replacebody.html">smfi_replacebody</A></TD><TD>Replace the 125254885Sdumbbellbody of the message.</TD><TD>SMFIF_CHGBODY</TD></TR> 126254885Sdumbbell 127254885Sdumbbell</TABLE> 128254885Sdumbbell 129254885Sdumbbell<H2>Other Message Handling Functions</H2> 130254885Sdumbbell 131254885SdumbbellThe following functions provide special case handling instructions for 132254885Sdumbbellmilter or the MTA, without altering the content or status of the message. 133254885Sdumbbell<EM>They too may only be called in <A HREF="xxfi_eom.html">xxfi_eom</A></EM>. 134254885SdumbbellAll of these functions may invoke additional communication with the MTA. 135254885SdumbbellThey will return either MI_SUCCESS or MI_FAILURE to indicate the status of 136254885Sdumbbellthe operation. 137254885Sdumbbell 138254885Sdumbbell<P> 139254885SdumbbellNote that the status returned indicates only whether or not the 140254885Sdumbbellfilter's message was successfully sent to the MTA, not whether or not 141254885Sdumbbellthe MTA performed the requested operation. 142254885Sdumbbell 143254885Sdumbbell<P> 144254885Sdumbbell<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 145254885Sdumbbell<TR><TD><A HREF="smfi_progress.html">smfi_progress</A></TD><TD>Report operation in progress.</TD></TR> 146254885Sdumbbell 147254885Sdumbbell<TR><TD><A HREF="smfi_quarantine.html">smfi_quarantine</A></TD><TD>Quarantine a message.</TD></TR> 148254885Sdumbbell 149254885Sdumbbell</TABLE> 150254885Sdumbbell 151254885Sdumbbell<H2><A NAME="Callbacks">Callbacks</A></H2> 152254885Sdumbbell 153254885SdumbbellThe filter should implement one or more of the following callbacks, 154254885Sdumbbellwhich are registered via <A HREF="smfi_register.html">smfi_register</A>: 155254885Sdumbbell 156254885Sdumbbell<P> 157254885Sdumbbell<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 158254885Sdumbbell 159254885Sdumbbell<TR><TD><A HREF="xxfi_connect.html">xxfi_connect</A></TD><TD>connection info</TD></TR> 160254885Sdumbbell 161254885Sdumbbell<TR><TD><A HREF="xxfi_helo.html">xxfi_helo</A></TD><TD>SMTP HELO/EHLO command</TD></TR> 162254885Sdumbbell 163254885Sdumbbell<TR><TD><A HREF="xxfi_envfrom.html">xxfi_envfrom</A></TD><TD>envelope sender</TD></TR> 164254885Sdumbbell 165254885Sdumbbell<TR><TD><A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A></TD><TD>envelope recipient</TD></TR> 166254885Sdumbbell 167254885Sdumbbell<TR><TD><A HREF="xxfi_data.html">xxfi_data</A></TD><TD>DATA command</TD></TR> 168254885Sdumbbell 169254885Sdumbbell<TR><TD><A HREF="xxfi_unknown.html">xxfi_unknown</A></TD><TD>Unknown SMTP command</TD></TR> 170254885Sdumbbell 171254885Sdumbbell<TR><TD><A HREF="xxfi_header.html">xxfi_header</A></TD><TD>header</TD></TR> 172254885Sdumbbell 173254885Sdumbbell<TR><TD><A HREF="xxfi_eoh.html">xxfi_eoh</A></TD><TD>end of header</TD></TR> 174254885Sdumbbell 175254885Sdumbbell<TR><TD><A HREF="xxfi_body.html">xxfi_body</A></TD><TD>body block</TD></TR> 176254885Sdumbbell 177254885Sdumbbell<TR><TD><A HREF="xxfi_eom.html">xxfi_eom</A></TD><TD>end of message</TD></TR> 178254885Sdumbbell 179254885Sdumbbell<TR><TD><A HREF="xxfi_abort.html">xxfi_abort</A></TD><TD>message aborted</TD></TR> 180254885Sdumbbell 181254885Sdumbbell<TR><TD><A HREF="xxfi_close.html">xxfi_close</A></TD><TD>connection cleanup</TD></TR> 182254885Sdumbbell 183254885Sdumbbell<TR><TD><A HREF="xxfi_negotiate.html">xxfi_negotiate</A></TD><TD>option negotiattion</TD></TR> 184254885Sdumbbell 185254885Sdumbbell</TABLE> 186254885Sdumbbell 187254885Sdumbbell<P> 188254885SdumbbellThe above callbacks should all return one of the following return values, 189254885Sdumbbellhaving the indicated meanings. Any return other than one of the below 190254885Sdumbbellvalues constitutes an error, and will cause sendmail to terminate its 191254885Sdumbbellconnection to the offending filter. 192254885Sdumbbell 193254885Sdumbbell<P><A NAME="conn-spec">Milter</A> distinguishes between recipient-, 194254885Sdumbbellmessage-, 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_abort.html">xxfi_abort</A>), reject this message.<BR> 218 For a recipient-oriented routine, reject the current recipient (but continue processing the current message). 219 </TD> 220 </TR> 221 <TR valign="top"> 222 <TD>SMFIS_DISCARD</TD> 223 <TD>For a message- or recipient-oriented routine, accept this message, but silently discard it.<BR> 224 SMFIS_DISCARD should not be returned by a connection-oriented routine. 225 </TD> 226 </TR> 227 <TR valign="top"> 228 <TD>SMFIS_ACCEPT</TD> 229 <TD>For a connection-oriented routine, accept this connection without further filter processing; call <A HREF="xxfi_close.html">xxfi_close</A>.<BR> 230 For a message- or recipient-oriented routine, accept this message without further filtering.<BR> 231 </TD> 232 </TR> 233 <TR valign="top"> 234 <TD>SMFIS_TEMPFAIL</TD> 235 <TD>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code. 236 For a message-oriented routine (except <A HREF="xxfi_envfrom.html">xxfi_envfrom</A>), fail for this message. <BR> 237 For a connection-oriented routine, fail for this connection; call <A HREF="xxfi_close.html">xxfi_close</A>. <BR> 238 For a recipient-oriented routine, only fail for the current recipient; continue message processing. 239 </TD> 240 </TR> 241 242 <TR valign="top"> 243 <TD><A NAME="SMFIS_SKIP">SMFIS_SKIP</A></TD> 244 <TD>Skip further callbacks of the same type in this transaction. 245 Currently this return value is only allowed in 246 <A HREF="xxfi_body.html">xxfi_body()</A>. 247 It can be used if a milter has received sufficiently many 248 body chunks to make a decision, but still wants to invoke 249 message modification functions that are only allowed to be called from 250 <A HREF="xxfi_eom.html">xxfi_eom()</A>. 251 Note: the milter <EM>must</EM> 252 <A HREF="xxfi_negotiate.html">negotiate</A> 253 this behavior with the MTA, i.e., it must check whether 254 the protocol action 255 <A HREF="xxfi_negotiate.html#SMFIP_SKIP"><CODE>SMFIP_SKIP</CODE></A> 256 is available and if so, the milter must request it. 257 </TD> 258 </TR> 259 260 <TR valign="top"> 261 <TD><A NAME="SMFIS_NOREPLY">SMFIS_NOREPLY</A></TD> 262 <TD>Do not send a reply back to the MTA. 263 The milter <EM>must</EM> 264 <A HREF="xxfi_negotiate.html">negotiate</A> 265 this behavior with the MTA, i.e., it must check whether 266 the appropriate protocol action 267 <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 268 is available and if so, the milter must request it. 269 If you set the 270 <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 271 protocol action for a callback, that callback <EM>must</EM> 272 always reply with 273 SMFIS_NOREPLY. 274 Using any other reply code is a violation of the API. 275 If in some cases your callback may return another value 276 (e.g., due to some resource shortages), then you 277 <EM>must not</EM> set 278 <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 279 and you must use 280 SMFIS_CONTINUE as the default return code. 281 (Alternatively you can try to delay reporting the problem to 282 a later callback for which 283 <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 284 is not set.) 285 </TD> 286 </TR> 287 288</TABLE> 289 290<H2><A NAME="Miscellaneous">Miscellaneous</A></H2> 291 292<P> 293<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> 294 295<TR><TD><A HREF="smfi_version.html">smfi_version</A></TD><TD>libmilter (runtime) version info</TD></TR> 296 297<TR><TD><A HREF="smfi_setsymlist.html">smfi_setsymlist</A></TD><TD> 298Set the list of macros that the milter wants to receive from the MTA 299for a protocol stage. 300</TD></TR> 301 302</TABLE> 303 304<P> 305<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Constant</TH><TH>Description</TH></TR> 306 307<TR><TD><A HREF="smfi_version.html">SMFI_VERSION</A></TD><TD>libmilter (compile time) version info</TD></TR> 308 309</TABLE> 310 311 312<HR SIZE="1"> 313<FONT SIZE="-1"> 314Copyright (c) 2000, 2003, 2006, 2009 Sendmail, Inc. and its suppliers. 315All rights reserved. 316<BR> 317By using this file, you agree to the terms and conditions set 318forth in the LICENSE. 319</FONT> 320</BODY> 321</HTML> 322