api.html revision 112810
1233294Sstas<html> 272445Sassar<head><title>Milter API</title></head> 3178825Sdfr<body> 472445Sassar<h1>Milter API</h1> 555682Smarkm 655682Smarkm<h2>Contents</h2> 7178825Sdfr<ul> 8178825Sdfr <li>Library Control Functions 9178825Sdfr <li>Data Access Functions 10178825Sdfr <li>Message Modification Functions 11178825Sdfr <li>Callbacks 12178825Sdfr</ul> 13178825Sdfr 1472445Sassar<h2>Library Control Functions</h2> 15178825Sdfr 16178825SdfrBefore handing control to libmilter (by calling <a 17178825Sdfrhref="smfi_main.html">smfi_main</a>), a filter may call the following 18178825Sdfrfunctions to set libmilter parameters. In particular, the filter must 19178825Sdfrcall <a href="smfi_register.html">smfi_register</a> to register its 20178825Sdfrcallbacks. Each function will return either MI_SUCCESS or MI_FAILURE to 21178825Sdfrindicate the status of the operation. 22178825Sdfr<p> 23178825SdfrNone of these functions communicate with the MTA. All alter the 24178825Sdfrlibrary's state, some of which is communicated to the MTA inside <a 25178825Sdfrhref="smfi_main.html">smfi_main</a>. 26233294Sstas<p> 27127808Snectar<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 28127808Snectar 29127808Snectar<tr><td><a href="smfi_register.html">smfi_register</a></td><td>Register a filter.</td></tr> 30178825Sdfr 31178825Sdfr<tr><td><a href="smfi_setconn.html">smfi_setconn</a></td><td>Specify socket to use.</td></tr> 32178825Sdfr 33233294Sstas<tr><td><a href="smfi_settimeout.html">smfi_settimeout</a></td><td>Set timeout.</td></tr> 3472445Sassar 3572445Sassar<tr><td><a href="smfi_main.html">smfi_main</a></td><td>Hand control to libmilter.</td></tr> 3672445Sassar 3755682Smarkm</table> 3855682Smarkm 3955682Smarkm<h2>Data Access Functions</h2> 4055682Smarkm 4155682SmarkmThe following functions may be called from within the filter-defined callbacks 4255682Smarkmto access information about the current connection or message. 4355682Smarkm<p> 4455682Smarkm<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 4555682Smarkm<tr><td><a href="smfi_getsymval.html">smfi_getsymval</a></td><td>Return the value 4655682Smarkmof a symbol.</td></tr> 4755682Smarkm 48178825Sdfr<tr><td><a href="smfi_getpriv.html">smfi_getpriv</a></td><td>Get the private data 4955682Smarkmpointer.</td></tr> 50178825Sdfr 51178825Sdfr<tr><td><a href="smfi_setpriv.html">smfi_setpriv</a></td><td>Set the private data 5255682Smarkmpointer.</td></tr> 5355682Smarkm 5455682Smarkm<tr><td><a href="smfi_setreply.html">smfi_setreply</a></td><td>Set the specific 5555682Smarkmreply code to be used.</td></tr> 5655682Smarkm 5755682Smarkm</table> 5855682Smarkm 5955682Smarkm<h2>Message Modification Functions</h2> 60178825Sdfr 6155682SmarkmThe following functions change a message's contents and attributes. 6255682Smarkm<b>They may only be called in <a href="xxfi_eom.html">xxfi_eom</a></b>. 6355682SmarkmAll of these functions may invoke additional communication with the MTA. 6455682SmarkmThey will return either MI_SUCCESS or MI_FAILURE to indicate the status of 6555682Smarkmthe operation. 6655682Smarkm 6755682Smarkm<p> 6855682SmarkmA filter must have set the appropriate flag (listed below) in the 6955682Smarkmdescription passed to <a href="smfi_register.html">smfi_register</a> 7055682Smarkmto call any message modification function. Failure to do so will 7155682Smarkmcause the MTA to treat a call to the function as a failure of the 7255682Smarkmfilter, terminating its connection. 73127808Snectar 7455682Smarkm<p> 7555682SmarkmNote that the status returned indicates only whether or not the 7655682Smarkmfilter's message was successfully sent to the MTA, not whether or not 7755682Smarkmthe MTA performed the requested operation. For example, <a 78127808Snectarhref="smfi_addheader.html">smfi_addheader</a>, when called with an 7955682Smarkmillegal header name, will return MI_SUCCESS even though the MTA may 80178825Sdfrlater refuse to add the illegal header. 8155682Smarkm<p> 8255682Smarkm<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th><th>SMFIF_* flag</tr> 8355682Smarkm<tr><td><a href="smfi_addheader.html">smfi_addheader</a></td><td>Add a header to 8455682Smarkmthe message.</td><td>SMFIF_ADDHDRS</td></tr> 8555682Smarkm 86127808Snectar<tr><td><a href="smfi_chgheader.html">smfi_chgheader</a></td><td>Change or delete a header.</td><td>SMFIF_CHGHDRS</td></tr> 8755682Smarkm 8855682Smarkm<tr><td><a href="smfi_addrcpt.html">smfi_addrcpt</a></td><td>Add a recipient to 8955682Smarkmthe envelope.</td><td>SMFIF_ADDRCPT</td></tr> 9055682Smarkm 9155682Smarkm<tr><td><a href="smfi_delrcpt.html">smfi_delrcpt</a></td><td>Delete a recipient 9255682Smarkmfrom the envelope.</td><td>SMFIF_DELRCPT</td></tr> 9355682Smarkm 94127808Snectar<tr><td><a href="smfi_replacebody.html">smfi_replacebody</a></td><td>Replace the 95127808Snectarbody of the message.</td><td>SMFIF_CHGBODY</td></tr> 96233294Sstas 97233294Sstas</table> 9855682Smarkm 9955682Smarkm<h2>Callbacks</h2> 10055682Smarkm 10155682SmarkmThe filter should implement one or more of the following callbacks, 10255682Smarkmwhich are registered via <a href="smfi_register.html">smfi_register</a>: 10355682Smarkm<p> 10455682Smarkm<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 105178825Sdfr 106178825Sdfr<tr><td><a href="xxfi_connect.html">xxfi_connect</a></td><td>connection info</td></tr> 10755682Smarkm 10855682Smarkm<tr><td><a href="xxfi_helo.html">xxfi_helo</a></td><td>SMTP HELO/EHLO command</td></tr> 109233294Sstas 110233294Sstas<tr><td><a href="xxfi_envfrom.html">xxfi_envfrom</a></td><td>envelope sender</td></tr> 111233294Sstas 112233294Sstas<tr><td><a href="xxfi_envrcpt.html">xxfi_envrcpt</a></td><td>envelope recipient</td></tr> 113233294Sstas 114233294Sstas<tr><td><a href="xxfi_header.html">xxfi_header</a></td><td>header</td></tr> 115233294Sstas 116233294Sstas<tr><td><a href="xxfi_eoh.html">xxfi_eoh</a></td><td>end of header</td></tr> 117178825Sdfr 11855682Smarkm<tr><td><a href="xxfi_body.html">xxfi_body</a></td><td>body block</td></tr> 11955682Smarkm 120127808Snectar<tr><td><a href="xxfi_eom.html">xxfi_eom</a></td><td>end of message</td></tr> 121178825Sdfr 122178825Sdfr<tr><td><a href="xxfi_abort.html">xxfi_abort</a></td><td>message aborted</td></tr> 12355682Smarkm 124127808Snectar<tr><td><a href="xxfi_close.html">xxfi_close</a></td><td>connection cleanup</td></tr> 125127808Snectar 126127808Snectar</table> 127127808Snectar 12855682Smarkm<p> 12955682SmarkmThe above callbacks should all return one of the following return values, 13055682Smarkmhaving the indicated meanings. Any return other than one of the below 13155682Smarkmvalues constitutes an error, and will cause sendmail to terminate its 13255682Smarkmconnection to the offending filter. 13355682Smarkm 13455682Smarkm<p><a name="conn-spec"></a>Milter distinguishes between recipient-, 13555682Smarkmmessage-, and connection-oriented routines. Recipient-oriented 136178825Sdfrcallbacks may affect the processing of a single message recipient; 137178825Sdfrmessage-oriented callbacks, a single message; connection-oriented 13855682Smarkmcallbacks, an entire connection (during which multiple messages may be 13955682Smarkmdelivered to multiple sets of recipients). 140178825Sdfr<a href="xxfi_envrcpt.html">xxfi_envrcpt</a> is recipient-oriented. 141178825Sdfr<a href="xxfi_connect.html">xxfi_connect</a>, 142178825Sdfr<a href="xxfi_helo.html">xxfi_helo</a> and 143178825Sdfr<a href="xxfi_close.html">xxfi_close</a> are connection-oriented. All 144178825Sdfrother callbacks are message-oriented. 145178825Sdfr 146178825Sdfr<p> 147178825Sdfr<table border="1" cellspacing=0 cellpadding=2> 148178825Sdfr <tr bgcolor="#dddddd"><th>Return value</th><th>Description</th></tr> 14955682Smarkm <tr valign="top"> 15055682Smarkm <td>SMFIS_CONTINUE</td> 15155682Smarkm <td>Continue processing the current connection, message, or recipient. 15255682Smarkm </td> 15355682Smarkm </tr> 154178825Sdfr <tr valign="top"> 15555682Smarkm <td>SMFIS_REJECT</td> 15655682Smarkm <td>For a connection-oriented routine, reject this connection; call <a href="xxfi_close.html">xxfi_close</a>.<br> 15755682Smarkm For a message-oriented routine (except 158178825Sdfr <a href="xxfi_eom.html">xxfi_eom</a> or 15955682Smarkm <a href="xxfi_abort.html">xxfi_abort</a>), reject this message.<br> 16055682Smarkm For a recipient-oriented routine, reject the current recipient (but continue processing the current message). 16155682Smarkm </td> 16255682Smarkm </tr> 16355682Smarkm <tr valign="top"> 16455682Smarkm <td>SMFIS_DISCARD</td> 16555682Smarkm <td>For a message- or recipient-oriented routine, accept this message, but silently discard it.<br> 166178825Sdfr SMFIS_DISCARD should not be returned by a connection-oriented routine. 16755682Smarkm </td> 16855682Smarkm </tr> 16955682Smarkm <tr valign="top"> 170178825Sdfr <td>SMFIS_ACCEPT</td> 171178825Sdfr <td>For a connection-oriented routine, accept this connection without further filter processing; call <a href="xxfi_close.html">xxfi_close</a>.<br> 17255682Smarkm For a message- or recipient-oriented routine, accept this message without further filtering.<br> 17355682Smarkm </td> 17455682Smarkm </tr> 17555682Smarkm <tr valign="top"> 17655682Smarkm <td>SMFIS_TEMPFAIL</td> 17755682Smarkm <td>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code. 17855682Smarkm For a message-oriented routine (except <a href="xxfi_envfrom.html">xxfi_envfrom</a>), fail for this message. <br> 17955682Smarkm For a connection-oriented routine, fail for this connection; call <a href="xxfi_close.html">xxfi_close</a>. <br> 18055682Smarkm For a recipient-oriented routine, only fail for the current recipient; continue message processing. 18155682Smarkm </td> 18255682Smarkm </tr> 18355682Smarkm</table> 18455682Smarkm 18555682Smarkm<hr size="1"> 18655682Smarkm<font size="-1"> 18755682SmarkmCopyright (c) 2000, 2003 Sendmail, Inc. and its suppliers. 18855682SmarkmAll rights reserved. 18955682Smarkm<br> 19055682SmarkmBy using this file, you agree to the terms and conditions set 19155682Smarkmforth in the LICENSE. 19255682Smarkm</font> 19355682Smarkm</body> 19455682Smarkm</html> 19555682Smarkm