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