1<html> 2<head><title>Milter API</title></head> 3<body> 4<!-- 5$Id: api.html,v 1.18 2004/04/28 23:26:51 msk Exp $ 6--> 7<h1>Milter API</h1> 8 9<h2>Contents</h2> 10<ul> 11 <li>Library Control Functions 12 <li>Data Access Functions 13 <li>Message Modification Functions 14 <li>Callbacks 15</ul> 16 17<h2>Library Control Functions</h2> 18 19Before handing control to libmilter (by calling <a 20href="smfi_main.html">smfi_main</a>), a filter may call the following 21functions to set libmilter parameters. In particular, the filter must 22call <a href="smfi_register.html">smfi_register</a> to register its 23callbacks. Each function will return either MI_SUCCESS or MI_FAILURE to 24indicate the status of the operation. 25<p> 26None of these functions communicate with the MTA. All alter the 27library's state, some of which is communicated to the MTA inside <a 28href="smfi_main.html">smfi_main</a>. 29<p> 30<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 31 32<tr><td><a href="smfi_opensocket.html">smfi_opensocket</a></td><td>Try to create the interface socket.</td></tr> 33 34<tr><td><a href="smfi_register.html">smfi_register</a></td><td>Register a filter.</td></tr> 35 36<tr><td><a href="smfi_setconn.html">smfi_setconn</a></td><td>Specify socket to use.</td></tr> 37 38<tr><td><a href="smfi_settimeout.html">smfi_settimeout</a></td><td>Set timeout.</td></tr> 39 40<tr><td><a href="smfi_setbacklog.html">smfi_setbacklog</a></td><td>Define the incoming <i>listen</i>(2) queue size.</td></tr> 41 42<tr><td><a href="smfi_setdbg.html">smfi_setdbg</a></td><td>Set the milter library debugging (tracing) level.</td></tr> 43 44<tr><td><a href="smfi_stop.html">smfi_stop</a></td><td>Cause an orderly shutdown.</td></tr> 45 46<tr><td><a href="smfi_main.html">smfi_main</a></td><td>Hand control to libmilter.</td></tr> 47 48</table> 49 50<h2>Data Access Functions</h2> 51 52The following functions may be called from within the filter-defined callbacks 53to access information about the current connection or message. 54<p> 55<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 56<tr><td><a href="smfi_getsymval.html">smfi_getsymval</a></td><td>Return the value 57of a symbol.</td></tr> 58 59<tr><td><a href="smfi_getpriv.html">smfi_getpriv</a></td><td>Get the private data 60pointer.</td></tr> 61 62<tr><td><a href="smfi_setpriv.html">smfi_setpriv</a></td><td>Set the private data 63pointer.</td></tr> 64 65<tr><td><a href="smfi_setreply.html">smfi_setreply</a></td><td>Set the specific 66reply code to be used.</td></tr> 67 68<tr><td><a href="smfi_setmlreply.html">smfi_setmlreply</a></td><td>Set the 69specific multi-line reply to be used.</td></tr> 70 71</table> 72 73<h2>Message Modification Functions</h2> 74 75The following functions change a message's contents and attributes. 76<b>They may only be called in <a href="xxfi_eom.html">xxfi_eom</a></b>. 77All of these functions may invoke additional communication with the MTA. 78They will return either MI_SUCCESS or MI_FAILURE to indicate the status of 79the operation. 80 81<p> 82A filter must have set the appropriate flag (listed below) in the 83description passed to <a href="smfi_register.html">smfi_register</a> 84to call any message modification function. Failure to do so will 85cause the MTA to treat a call to the function as a failure of the 86filter, terminating its connection. 87 88<p> 89Note that the status returned indicates only whether or not the 90filter's message was successfully sent to the MTA, not whether or not 91the MTA performed the requested operation. For example, <a 92href="smfi_addheader.html">smfi_addheader</a>, when called with an 93illegal header name, will return MI_SUCCESS even though the MTA may 94later refuse to add the illegal header. 95<p> 96<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th><th>SMFIF_* flag</tr> 97<tr><td><a href="smfi_addheader.html">smfi_addheader</a></td><td>Add a header to 98the message.</td><td>SMFIF_ADDHDRS</td></tr> 99 100<tr><td><a href="smfi_chgheader.html">smfi_chgheader</a></td><td>Change or delete a header.</td><td>SMFIF_CHGHDRS</td></tr> 101 102<tr><td><a href="smfi_insheader.html">smfi_insheader</a></td><td>Insert a 103header into the message.</td><td>SMFIF_ADDHDRS</td></tr> 104 105<tr><td><a href="smfi_addrcpt.html">smfi_addrcpt</a></td><td>Add a recipient to 106the envelope.</td><td>SMFIF_ADDRCPT</td></tr> 107 108<tr><td><a href="smfi_delrcpt.html">smfi_delrcpt</a></td><td>Delete a recipient 109from the envelope.</td><td>SMFIF_DELRCPT</td></tr> 110 111<tr><td><a href="smfi_replacebody.html">smfi_replacebody</a></td><td>Replace the 112body of the message.</td><td>SMFIF_CHGBODY</td></tr> 113 114</table> 115 116<h2>Other Message Handling Functions</h2> 117 118The following functions provide special case handling instructions for 119milter or the MTA, without altering the content or status of the message. 120<b>They too may only be called in <a href="xxfi_eom.html">xxfi_eom</a></b>. 121All of these functions may invoke additional communication with the MTA. 122They will return either MI_SUCCESS or MI_FAILURE to indicate the status of 123the operation. 124 125<p> 126Note that the status returned indicates only whether or not the 127filter's message was successfully sent to the MTA, not whether or not 128the MTA performed the requested operation. 129 130<p> 131<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 132<tr><td><a href="smfi_progress.html">smfi_progress</a></td><td>Report operation in progress.</td></tr> 133 134<tr><td><a href="smfi_quarantine.html">smfi_quarantine</a></td><td>Quarantine a message.</td></tr> 135 136</table> 137 138<h2><a name="callbacks">Callbacks</a></h2> 139 140The filter should implement one or more of the following callbacks, 141which are registered via <a href="smfi_register.html">smfi_register</a>: 142<p> 143<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 144 145<tr><td><a href="xxfi_connect.html">xxfi_connect</a></td><td>connection info</td></tr> 146 147<tr><td><a href="xxfi_helo.html">xxfi_helo</a></td><td>SMTP HELO/EHLO command</td></tr> 148 149<tr><td><a href="xxfi_envfrom.html">xxfi_envfrom</a></td><td>envelope sender</td></tr> 150 151<tr><td><a href="xxfi_envrcpt.html">xxfi_envrcpt</a></td><td>envelope recipient</td></tr> 152 153<tr><td><a href="xxfi_header.html">xxfi_header</a></td><td>header</td></tr> 154 155<tr><td><a href="xxfi_eoh.html">xxfi_eoh</a></td><td>end of header</td></tr> 156 157<tr><td><a href="xxfi_body.html">xxfi_body</a></td><td>body block</td></tr> 158 159<tr><td><a href="xxfi_eom.html">xxfi_eom</a></td><td>end of message</td></tr> 160 161<tr><td><a href="xxfi_abort.html">xxfi_abort</a></td><td>message aborted</td></tr> 162 163<tr><td><a href="xxfi_close.html">xxfi_close</a></td><td>connection cleanup</td></tr> 164 165</table> 166 167<p> 168The above callbacks should all return one of the following return values, 169having the indicated meanings. Any return other than one of the below 170values constitutes an error, and will cause sendmail to terminate its 171connection to the offending filter. 172 173<p><a name="conn-spec">Milter</a> distinguishes between recipient-, 174message-, and connection-oriented routines. Recipient-oriented 175callbacks may affect the processing of a single message recipient; 176message-oriented callbacks, a single message; connection-oriented 177callbacks, an entire connection (during which multiple messages may be 178delivered to multiple sets of recipients). 179<a href="xxfi_envrcpt.html">xxfi_envrcpt</a> is recipient-oriented. 180<a href="xxfi_connect.html">xxfi_connect</a>, 181<a href="xxfi_helo.html">xxfi_helo</a> and 182<a href="xxfi_close.html">xxfi_close</a> are connection-oriented. All 183other callbacks are message-oriented. 184 185<p> 186<table border="1" cellspacing=0 cellpadding=2> 187 <tr bgcolor="#dddddd"><th>Return value</th><th>Description</th></tr> 188 <tr valign="top"> 189 <td>SMFIS_CONTINUE</td> 190 <td>Continue processing the current connection, message, or recipient. 191 </td> 192 </tr> 193 <tr valign="top"> 194 <td>SMFIS_REJECT</td> 195 <td>For a connection-oriented routine, reject this connection; call <a href="xxfi_close.html">xxfi_close</a>.<br> 196 For a message-oriented routine (except 197 <a href="xxfi_eom.html">xxfi_eom</a> or 198 <a href="xxfi_abort.html">xxfi_abort</a>), reject this message.<br> 199 For a recipient-oriented routine, reject the current recipient (but continue processing the current message). 200 </td> 201 </tr> 202 <tr valign="top"> 203 <td>SMFIS_DISCARD</td> 204 <td>For a message- or recipient-oriented routine, accept this message, but silently discard it.<br> 205 SMFIS_DISCARD should not be returned by a connection-oriented routine. 206 </td> 207 </tr> 208 <tr valign="top"> 209 <td>SMFIS_ACCEPT</td> 210 <td>For a connection-oriented routine, accept this connection without further filter processing; call <a href="xxfi_close.html">xxfi_close</a>.<br> 211 For a message- or recipient-oriented routine, accept this message without further filtering.<br> 212 </td> 213 </tr> 214 <tr valign="top"> 215 <td>SMFIS_TEMPFAIL</td> 216 <td>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code. 217 For a message-oriented routine (except <a href="xxfi_envfrom.html">xxfi_envfrom</a>), fail for this message. <br> 218 For a connection-oriented routine, fail for this connection; call <a href="xxfi_close.html">xxfi_close</a>. <br> 219 For a recipient-oriented routine, only fail for the current recipient; continue message processing. 220 </td> 221 </tr> 222</table> 223 224<hr size="1"> 225<font size="-1"> 226Copyright (c) 2000, 2003 Sendmail, Inc. and its suppliers. 227All rights reserved. 228<br> 229By using this file, you agree to the terms and conditions set 230forth in the LICENSE. 231</font> 232</body> 233</html> 234