api.html revision 90792
190792Sgshapiro<html> 290792Sgshapiro<head><title>Milter API</title></head> 390792Sgshapiro<body> 490792Sgshapiro<h1>Milter API</h1> 590792Sgshapiro 690792Sgshapiro<h2>Contents</h2> 790792Sgshapiro<ul> 890792Sgshapiro <li>Library Control Functions 990792Sgshapiro <li>Data Access Functions 1090792Sgshapiro <li>Message Modification Functions 1190792Sgshapiro <li>Callbacks 1290792Sgshapiro</ul> 1390792Sgshapiro 1490792Sgshapiro<h2>Library Control Functions</h2> 1590792Sgshapiro 1690792SgshapiroBefore handing control to libmilter (by calling <a 1790792Sgshapirohref="smfi_main.html">smfi_main</a>), a filter may call the following 1890792Sgshapirofunctions to set libmilter parameters. In particular, the filter must 1990792Sgshapirocall <a href="smfi_register.html">smfi_register</a> to register its 2090792Sgshapirocallbacks. Each function will return either MI_SUCCESS or MI_FAILURE to 2190792Sgshapiroindicate the status of the operation. 2290792Sgshapiro<p> 2390792SgshapiroNone of these functions communicate with the MTA. All alter the 2490792Sgshapirolibrary's state, some of which is communicated to the MTA inside <a 2590792Sgshapirohref="smfi_main.html">smfi_main</a>. 2690792Sgshapiro<p> 2790792Sgshapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 2890792Sgshapiro 2990792Sgshapiro<tr><td><a href="smfi_register.html">smfi_register</a></td><td>Register a filter.</td></tr> 3090792Sgshapiro 3190792Sgshapiro<tr><td><a href="smfi_setconn.html">smfi_setconn</a></td><td>Specify socket to use.</td></tr> 3290792Sgshapiro 3390792Sgshapiro<tr><td><a href="smfi_settimeout.html">smfi_settimeout</a></td><td>Set timeout.</td></tr> 3490792Sgshapiro 3590792Sgshapiro<tr><td><a href="smfi_main.html">smfi_main</a></td><td>Hand control to libmilter.</td></tr> 3690792Sgshapiro 3790792Sgshapiro</table> 3890792Sgshapiro 3990792Sgshapiro<h2>Data Access Functions</h2> 4090792Sgshapiro 4190792SgshapiroThe following functions may be called from within the filter-defined callbacks 4290792Sgshapiroto access information about the current connection or message. 4390792Sgshapiro<p> 4490792Sgshapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 4590792Sgshapiro<tr><td><a href="smfi_getsymval.html">smfi_getsymval</a></td><td>Return the value 4690792Sgshapiroof a symbol.</td></tr> 4790792Sgshapiro 4890792Sgshapiro<tr><td><a href="smfi_getpriv.html">smfi_getpriv</a></td><td>Get the private data 4990792Sgshapiropointer.</td></tr> 5090792Sgshapiro 5190792Sgshapiro<tr><td><a href="smfi_setpriv.html">smfi_setpriv</a></td><td>Set the private data 5290792Sgshapiropointer.</td></tr> 5390792Sgshapiro 5490792Sgshapiro<tr><td><a href="smfi_setreply.html">smfi_setreply</a></td><td>Set the specific 5590792Sgshapiroreply code to be used.</td></tr> 5690792Sgshapiro 5790792Sgshapiro</table> 5890792Sgshapiro 5990792Sgshapiro<h2>Message Modification Functions</h2> 6090792Sgshapiro 6190792SgshapiroThe following functions change a message's contents and attributes. 6290792Sgshapiro<b>They may only be called in <a href="xxfi_eom.html">xxfi_eom</a></b>. 6390792SgshapiroAll of these functions may invoke additional communication with the MTA. 6490792SgshapiroThey will return either MI_SUCCESS or MI_FAILURE to indicate the status of 6590792Sgshapirothe operation. 6690792Sgshapiro 6790792Sgshapiro<p> 6890792SgshapiroA filter must have set the appropriate flag (listed below) in the 6990792Sgshapirodescription passed to <a href="smfi_register.html">smfi_register</a> 7090792Sgshapiroto call any message modification function. Failure to do so will 7190792Sgshapirocause the MTA to treat a call to the function as a failure of the 7290792Sgshapirofilter, terminating its connection. 7390792Sgshapiro 7490792Sgshapiro<p> 7590792SgshapiroNote that the status returned indicates only whether or not the 7690792Sgshapirofilter's message was successfully sent to the MTA, not whether or not 7790792Sgshapirothe MTA performed the requested operation. For example, <a 7890792Sgshapirohref="smfi_addheader.html">smfi_addheader</a>, when called with an 7990792Sgshapiroillegal header name, will return MI_SUCCESS even though the MTA may 8090792Sgshapirolater refuse to add the illegal header. 8190792Sgshapiro<p> 8290792Sgshapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th><th>SMFIF_* flag</tr> 8390792Sgshapiro<tr><td><a href="smfi_addheader.html">smfi_addheader</a></td><td>Add a header to 8490792Sgshapirothe message.</td><td>SMFIF_ADDHDRS</td></tr> 8590792Sgshapiro 8690792Sgshapiro<tr><td><a href="smfi_chgheader.html">smfi_chgheader</a></td><td>Change or delete a header.</td><td>SMFIF_CHGHDRS</td></tr> 8790792Sgshapiro 8890792Sgshapiro<tr><td><a href="smfi_addrcpt.html">smfi_addrcpt</a></td><td>Add a recipient to 8990792Sgshapirothe envelope.</td><td>SMFIF_ADDRCPT</td></tr> 9090792Sgshapiro 9190792Sgshapiro<tr><td><a href="smfi_delrcpt.html">smfi_delrcpt</a></td><td>Delete a recipient 9290792Sgshapirofrom the envelope.</td><td>SMFIF_DELRCPT</td></tr> 9390792Sgshapiro 9490792Sgshapiro<tr><td><a href="smfi_replacebody.html">smfi_replacebody</a></td><td>Replace the 9590792Sgshapirobody of the message.</td><td>SMFIF_CHGBODY</td></tr> 9690792Sgshapiro 9790792Sgshapiro</table> 9890792Sgshapiro 9990792Sgshapiro<h2>Callbacks</h2> 10090792Sgshapiro 10190792SgshapiroThe filter should implement one or more of the following callbacks, 10290792Sgshapirowhich are registered via <a href="smfi_register.html">smfi_register</a>: 10390792Sgshapiro<p> 10490792Sgshapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 10590792Sgshapiro 10690792Sgshapiro<tr><td><a href="xxfi_connect.html">xxfi_connect</a></td><td>connection info</td></tr> 10790792Sgshapiro 10890792Sgshapiro<tr><td><a href="xxfi_helo.html">xxfi_helo</a></td><td>SMTP HELO/EHLO command</td></tr> 10990792Sgshapiro 11090792Sgshapiro<tr><td><a href="xxfi_envfrom.html">xxfi_envfrom</a></td><td>envelope sender</td></tr> 11190792Sgshapiro 11290792Sgshapiro<tr><td><a href="xxfi_envrcpt.html">xxfi_envrcpt</a></td><td>envelope recipient</td></tr> 11390792Sgshapiro 11490792Sgshapiro<tr><td><a href="xxfi_header.html">xxfi_header</a></td><td>header</td></tr> 11590792Sgshapiro 11690792Sgshapiro<tr><td><a href="xxfi_eoh.html">xxfi_eoh</a></td><td>end of header</td></tr> 11790792Sgshapiro 11890792Sgshapiro<tr><td><a href="xxfi_body.html">xxfi_body</a></td><td>body block</td></tr> 11990792Sgshapiro 12090792Sgshapiro<tr><td><a href="xxfi_eom.html">xxfi_eom</a></td><td>end of message</td></tr> 12190792Sgshapiro 12290792Sgshapiro<tr><td><a href="xxfi_abort.html">xxfi_abort</a></td><td>message aborted</td></tr> 12390792Sgshapiro 12490792Sgshapiro<tr><td><a href="xxfi_close.html">xxfi_close</a></td><td>connection cleanup</td></tr> 12590792Sgshapiro 12690792Sgshapiro</table> 12790792Sgshapiro 12890792Sgshapiro<p> 12990792SgshapiroThe above callbacks should all return one of the following return values, 13090792Sgshapirohaving the indicated meanings. Any return other than one of the below 13190792Sgshapirovalues constitutes an error, and will cause sendmail to terminate its 13290792Sgshapiroconnection to the offending filter. 13390792Sgshapiro 13490792Sgshapiro<p><a name="conn-spec"></a>Milter distinguishes between recipient-, 13590792Sgshapiromessage-, and connection-oriented routines. Recipient-oriented 13690792Sgshapirocallbacks may affect the processing of a single message recipient; 13790792Sgshapiromessage-oriented callbacks, a single message; connection-oriented 13890792Sgshapirocallbacks, an entire connection (during which multiple messages may be 13990792Sgshapirodelivered to multiple sets of recipients). 14090792Sgshapiro<a href="xxfi_envrcpt.html">xxfi_envrcpt</a> is recipient-oriented. 14190792Sgshapiro<a href="xxfi_connect.html">xxfi_connect</a>, 14290792Sgshapiro<a href="xxfi_helo.html">xxfi_helo</a> and 14390792Sgshapiro<a href="xxfi_close.html">xxfi_close</a> are connection-oriented. All 14490792Sgshapiroother callbacks are message-oriented. 14590792Sgshapiro 14690792Sgshapiro<p> 14790792Sgshapiro<table border="1" cellspacing=0 cellpadding=2> 14890792Sgshapiro <tr bgcolor="#dddddd"><th>Return value</th><th>Description</th></tr> 14990792Sgshapiro <tr valign="top"> 15090792Sgshapiro <td>SMFIS_CONTINUE</td> 15190792Sgshapiro <td>Continue processing the current connection, message, or recipient. 15290792Sgshapiro </td> 15390792Sgshapiro </tr> 15490792Sgshapiro <tr valign="top"> 15590792Sgshapiro <td>SMFIS_REJECT</td> 15690792Sgshapiro <td>For a connection-oriented routine, reject this connection; call <a href="xxfi_close.html">xxfi_close</a>.<br> 15790792Sgshapiro For a message-oriented routine (except 15890792Sgshapiro <a href="xxfi_eom.html">xxfi_eom</a> or 15990792Sgshapiro <a href="xxfi_abort.html">xxfi_abort</a>), reject this message.<br> 16090792Sgshapiro For a recipient-oriented routine, reject the current recipient (but continue processing the current message). 16190792Sgshapiro </td> 16290792Sgshapiro </tr> 16390792Sgshapiro <tr valign="top"> 16490792Sgshapiro <td>SMFIS_DISCARD</td> 16590792Sgshapiro <td>For a message- or recipient-oriented routine, accept this message, but silently discard it.<br> 16690792Sgshapiro SMFIS_DISCARD should not be returned by a connection-oriented routine. 16790792Sgshapiro </td> 16890792Sgshapiro </tr> 16990792Sgshapiro <tr valign="top"> 17090792Sgshapiro <td>SMFIS_ACCEPT</td> 17190792Sgshapiro <td>For a connection-oriented routine, accept this connection without further filter processing; call <a href="xxfi_close.html">xxfi_close</a>.<br> 17290792Sgshapiro For a message- or recipient-oriented routine, accept this message without further filtering.<br> 17390792Sgshapiro </td> 17490792Sgshapiro </tr> 17590792Sgshapiro <tr valign="top"> 17690792Sgshapiro <td>SMFIS_TEMPFAIL</td> 17790792Sgshapiro <td>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code. 17890792Sgshapiro For a message-oriented routine (except <a href="xxfi_envfrom.html">xxfi_envfrom</a>), fail for this message. <br> 17990792Sgshapiro For a connection-oriented routine, fail for this connection; call <a href="xxfi_close.html">xxfi_close</a>. <br> 18090792Sgshapiro For a recipient-oriented routine, only fail for the current recipient; continue message processing. 18190792Sgshapiro </td> 18290792Sgshapiro </tr> 18390792Sgshapiro</table> 18490792Sgshapiro 18590792Sgshapiro<hr size="1"> 18690792Sgshapiro<font size="-1"> 18790792SgshapiroCopyright (c) 2000 Sendmail, Inc. and its suppliers. 18890792SgshapiroAll rights reserved. 18990792Sgshapiro<br> 19090792SgshapiroBy using this file, you agree to the terms and conditions set 19190792Sgshapiroforth in the <a href="LICENSE.txt">LICENSE</a>. 19290792Sgshapiro</font> 19390792Sgshapiro</body> 19490792Sgshapiro</html> 195