api.html revision 132943
190792Sgshapiro<html> 290792Sgshapiro<head><title>Milter API</title></head> 390792Sgshapiro<body> 4132943Sgshapiro<!-- 5132943Sgshapiro$Id: api.html,v 1.18 2004/04/28 23:26:51 msk Exp $ 6132943Sgshapiro--> 790792Sgshapiro<h1>Milter API</h1> 890792Sgshapiro 990792Sgshapiro<h2>Contents</h2> 1090792Sgshapiro<ul> 1190792Sgshapiro <li>Library Control Functions 1290792Sgshapiro <li>Data Access Functions 1390792Sgshapiro <li>Message Modification Functions 1490792Sgshapiro <li>Callbacks 1590792Sgshapiro</ul> 1690792Sgshapiro 1790792Sgshapiro<h2>Library Control Functions</h2> 1890792Sgshapiro 1990792SgshapiroBefore handing control to libmilter (by calling <a 2090792Sgshapirohref="smfi_main.html">smfi_main</a>), a filter may call the following 2190792Sgshapirofunctions to set libmilter parameters. In particular, the filter must 2290792Sgshapirocall <a href="smfi_register.html">smfi_register</a> to register its 2390792Sgshapirocallbacks. Each function will return either MI_SUCCESS or MI_FAILURE to 2490792Sgshapiroindicate the status of the operation. 2590792Sgshapiro<p> 2690792SgshapiroNone of these functions communicate with the MTA. All alter the 2790792Sgshapirolibrary's state, some of which is communicated to the MTA inside <a 2890792Sgshapirohref="smfi_main.html">smfi_main</a>. 2990792Sgshapiro<p> 3090792Sgshapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 3190792Sgshapiro 32132943Sgshapiro<tr><td><a href="smfi_opensocket.html">smfi_opensocket</a></td><td>Try to create the interface socket.</td></tr> 33132943Sgshapiro 3490792Sgshapiro<tr><td><a href="smfi_register.html">smfi_register</a></td><td>Register a filter.</td></tr> 3590792Sgshapiro 3690792Sgshapiro<tr><td><a href="smfi_setconn.html">smfi_setconn</a></td><td>Specify socket to use.</td></tr> 3790792Sgshapiro 3890792Sgshapiro<tr><td><a href="smfi_settimeout.html">smfi_settimeout</a></td><td>Set timeout.</td></tr> 3990792Sgshapiro 40132943Sgshapiro<tr><td><a href="smfi_setbacklog.html">smfi_setbacklog</a></td><td>Define the incoming <i>listen</i>(2) queue size.</td></tr> 41132943Sgshapiro 42132943Sgshapiro<tr><td><a href="smfi_setdbg.html">smfi_setdbg</a></td><td>Set the milter library debugging (tracing) level.</td></tr> 43132943Sgshapiro 44132943Sgshapiro<tr><td><a href="smfi_stop.html">smfi_stop</a></td><td>Cause an orderly shutdown.</td></tr> 45132943Sgshapiro 4690792Sgshapiro<tr><td><a href="smfi_main.html">smfi_main</a></td><td>Hand control to libmilter.</td></tr> 4790792Sgshapiro 4890792Sgshapiro</table> 4990792Sgshapiro 5090792Sgshapiro<h2>Data Access Functions</h2> 5190792Sgshapiro 5290792SgshapiroThe following functions may be called from within the filter-defined callbacks 5390792Sgshapiroto access information about the current connection or message. 5490792Sgshapiro<p> 5590792Sgshapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 5690792Sgshapiro<tr><td><a href="smfi_getsymval.html">smfi_getsymval</a></td><td>Return the value 5790792Sgshapiroof a symbol.</td></tr> 5890792Sgshapiro 5990792Sgshapiro<tr><td><a href="smfi_getpriv.html">smfi_getpriv</a></td><td>Get the private data 6090792Sgshapiropointer.</td></tr> 6190792Sgshapiro 6290792Sgshapiro<tr><td><a href="smfi_setpriv.html">smfi_setpriv</a></td><td>Set the private data 6390792Sgshapiropointer.</td></tr> 6490792Sgshapiro 6590792Sgshapiro<tr><td><a href="smfi_setreply.html">smfi_setreply</a></td><td>Set the specific 6690792Sgshapiroreply code to be used.</td></tr> 6790792Sgshapiro 68132943Sgshapiro<tr><td><a href="smfi_setmlreply.html">smfi_setmlreply</a></td><td>Set the 69132943Sgshapirospecific multi-line reply to be used.</td></tr> 70132943Sgshapiro 7190792Sgshapiro</table> 7290792Sgshapiro 7390792Sgshapiro<h2>Message Modification Functions</h2> 7490792Sgshapiro 7590792SgshapiroThe following functions change a message's contents and attributes. 7690792Sgshapiro<b>They may only be called in <a href="xxfi_eom.html">xxfi_eom</a></b>. 7790792SgshapiroAll of these functions may invoke additional communication with the MTA. 7890792SgshapiroThey will return either MI_SUCCESS or MI_FAILURE to indicate the status of 7990792Sgshapirothe operation. 8090792Sgshapiro 8190792Sgshapiro<p> 8290792SgshapiroA filter must have set the appropriate flag (listed below) in the 8390792Sgshapirodescription passed to <a href="smfi_register.html">smfi_register</a> 8490792Sgshapiroto call any message modification function. Failure to do so will 8590792Sgshapirocause the MTA to treat a call to the function as a failure of the 8690792Sgshapirofilter, terminating its connection. 8790792Sgshapiro 8890792Sgshapiro<p> 8990792SgshapiroNote that the status returned indicates only whether or not the 9090792Sgshapirofilter's message was successfully sent to the MTA, not whether or not 9190792Sgshapirothe MTA performed the requested operation. For example, <a 9290792Sgshapirohref="smfi_addheader.html">smfi_addheader</a>, when called with an 9390792Sgshapiroillegal header name, will return MI_SUCCESS even though the MTA may 9490792Sgshapirolater refuse to add the illegal header. 9590792Sgshapiro<p> 9690792Sgshapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th><th>SMFIF_* flag</tr> 9790792Sgshapiro<tr><td><a href="smfi_addheader.html">smfi_addheader</a></td><td>Add a header to 9890792Sgshapirothe message.</td><td>SMFIF_ADDHDRS</td></tr> 9990792Sgshapiro 10090792Sgshapiro<tr><td><a href="smfi_chgheader.html">smfi_chgheader</a></td><td>Change or delete a header.</td><td>SMFIF_CHGHDRS</td></tr> 10190792Sgshapiro 102132943Sgshapiro<tr><td><a href="smfi_insheader.html">smfi_insheader</a></td><td>Insert a 103132943Sgshapiroheader into the message.</td><td>SMFIF_ADDHDRS</td></tr> 104132943Sgshapiro 10590792Sgshapiro<tr><td><a href="smfi_addrcpt.html">smfi_addrcpt</a></td><td>Add a recipient to 10690792Sgshapirothe envelope.</td><td>SMFIF_ADDRCPT</td></tr> 10790792Sgshapiro 10890792Sgshapiro<tr><td><a href="smfi_delrcpt.html">smfi_delrcpt</a></td><td>Delete a recipient 10990792Sgshapirofrom the envelope.</td><td>SMFIF_DELRCPT</td></tr> 11090792Sgshapiro 11190792Sgshapiro<tr><td><a href="smfi_replacebody.html">smfi_replacebody</a></td><td>Replace the 11290792Sgshapirobody of the message.</td><td>SMFIF_CHGBODY</td></tr> 11390792Sgshapiro 11490792Sgshapiro</table> 11590792Sgshapiro 116132943Sgshapiro<h2>Other Message Handling Functions</h2> 11790792Sgshapiro 118132943SgshapiroThe following functions provide special case handling instructions for 119132943Sgshapiromilter or the MTA, without altering the content or status of the message. 120132943Sgshapiro<b>They too may only be called in <a href="xxfi_eom.html">xxfi_eom</a></b>. 121132943SgshapiroAll of these functions may invoke additional communication with the MTA. 122132943SgshapiroThey will return either MI_SUCCESS or MI_FAILURE to indicate the status of 123132943Sgshapirothe operation. 124132943Sgshapiro 125132943Sgshapiro<p> 126132943SgshapiroNote that the status returned indicates only whether or not the 127132943Sgshapirofilter's message was successfully sent to the MTA, not whether or not 128132943Sgshapirothe MTA performed the requested operation. 129132943Sgshapiro 130132943Sgshapiro<p> 131132943Sgshapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 132132943Sgshapiro<tr><td><a href="smfi_progress.html">smfi_progress</a></td><td>Report operation in progress.</td></tr> 133132943Sgshapiro 134132943Sgshapiro<tr><td><a href="smfi_quarantine.html">smfi_quarantine</a></td><td>Quarantine a message.</td></tr> 135132943Sgshapiro 136132943Sgshapiro</table> 137132943Sgshapiro 138132943Sgshapiro<h2><a name="callbacks">Callbacks</a></h2> 139132943Sgshapiro 14090792SgshapiroThe filter should implement one or more of the following callbacks, 14190792Sgshapirowhich are registered via <a href="smfi_register.html">smfi_register</a>: 14290792Sgshapiro<p> 14390792Sgshapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 14490792Sgshapiro 14590792Sgshapiro<tr><td><a href="xxfi_connect.html">xxfi_connect</a></td><td>connection info</td></tr> 14690792Sgshapiro 14790792Sgshapiro<tr><td><a href="xxfi_helo.html">xxfi_helo</a></td><td>SMTP HELO/EHLO command</td></tr> 14890792Sgshapiro 14990792Sgshapiro<tr><td><a href="xxfi_envfrom.html">xxfi_envfrom</a></td><td>envelope sender</td></tr> 15090792Sgshapiro 15190792Sgshapiro<tr><td><a href="xxfi_envrcpt.html">xxfi_envrcpt</a></td><td>envelope recipient</td></tr> 15290792Sgshapiro 15390792Sgshapiro<tr><td><a href="xxfi_header.html">xxfi_header</a></td><td>header</td></tr> 15490792Sgshapiro 15590792Sgshapiro<tr><td><a href="xxfi_eoh.html">xxfi_eoh</a></td><td>end of header</td></tr> 15690792Sgshapiro 15790792Sgshapiro<tr><td><a href="xxfi_body.html">xxfi_body</a></td><td>body block</td></tr> 15890792Sgshapiro 15990792Sgshapiro<tr><td><a href="xxfi_eom.html">xxfi_eom</a></td><td>end of message</td></tr> 16090792Sgshapiro 16190792Sgshapiro<tr><td><a href="xxfi_abort.html">xxfi_abort</a></td><td>message aborted</td></tr> 16290792Sgshapiro 16390792Sgshapiro<tr><td><a href="xxfi_close.html">xxfi_close</a></td><td>connection cleanup</td></tr> 16490792Sgshapiro 16590792Sgshapiro</table> 16690792Sgshapiro 16790792Sgshapiro<p> 16890792SgshapiroThe above callbacks should all return one of the following return values, 16990792Sgshapirohaving the indicated meanings. Any return other than one of the below 17090792Sgshapirovalues constitutes an error, and will cause sendmail to terminate its 17190792Sgshapiroconnection to the offending filter. 17290792Sgshapiro 173132943Sgshapiro<p><a name="conn-spec">Milter</a> distinguishes between recipient-, 17490792Sgshapiromessage-, and connection-oriented routines. Recipient-oriented 17590792Sgshapirocallbacks may affect the processing of a single message recipient; 17690792Sgshapiromessage-oriented callbacks, a single message; connection-oriented 17790792Sgshapirocallbacks, an entire connection (during which multiple messages may be 17890792Sgshapirodelivered to multiple sets of recipients). 17990792Sgshapiro<a href="xxfi_envrcpt.html">xxfi_envrcpt</a> is recipient-oriented. 18090792Sgshapiro<a href="xxfi_connect.html">xxfi_connect</a>, 18190792Sgshapiro<a href="xxfi_helo.html">xxfi_helo</a> and 18290792Sgshapiro<a href="xxfi_close.html">xxfi_close</a> are connection-oriented. All 18390792Sgshapiroother callbacks are message-oriented. 18490792Sgshapiro 18590792Sgshapiro<p> 18690792Sgshapiro<table border="1" cellspacing=0 cellpadding=2> 18790792Sgshapiro <tr bgcolor="#dddddd"><th>Return value</th><th>Description</th></tr> 18890792Sgshapiro <tr valign="top"> 18990792Sgshapiro <td>SMFIS_CONTINUE</td> 19090792Sgshapiro <td>Continue processing the current connection, message, or recipient. 19190792Sgshapiro </td> 19290792Sgshapiro </tr> 19390792Sgshapiro <tr valign="top"> 19490792Sgshapiro <td>SMFIS_REJECT</td> 19590792Sgshapiro <td>For a connection-oriented routine, reject this connection; call <a href="xxfi_close.html">xxfi_close</a>.<br> 19690792Sgshapiro For a message-oriented routine (except 19790792Sgshapiro <a href="xxfi_eom.html">xxfi_eom</a> or 19890792Sgshapiro <a href="xxfi_abort.html">xxfi_abort</a>), reject this message.<br> 19990792Sgshapiro For a recipient-oriented routine, reject the current recipient (but continue processing the current message). 20090792Sgshapiro </td> 20190792Sgshapiro </tr> 20290792Sgshapiro <tr valign="top"> 20390792Sgshapiro <td>SMFIS_DISCARD</td> 20490792Sgshapiro <td>For a message- or recipient-oriented routine, accept this message, but silently discard it.<br> 20590792Sgshapiro SMFIS_DISCARD should not be returned by a connection-oriented routine. 20690792Sgshapiro </td> 20790792Sgshapiro </tr> 20890792Sgshapiro <tr valign="top"> 20990792Sgshapiro <td>SMFIS_ACCEPT</td> 21090792Sgshapiro <td>For a connection-oriented routine, accept this connection without further filter processing; call <a href="xxfi_close.html">xxfi_close</a>.<br> 21190792Sgshapiro For a message- or recipient-oriented routine, accept this message without further filtering.<br> 21290792Sgshapiro </td> 21390792Sgshapiro </tr> 21490792Sgshapiro <tr valign="top"> 21590792Sgshapiro <td>SMFIS_TEMPFAIL</td> 21690792Sgshapiro <td>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code. 21790792Sgshapiro For a message-oriented routine (except <a href="xxfi_envfrom.html">xxfi_envfrom</a>), fail for this message. <br> 21890792Sgshapiro For a connection-oriented routine, fail for this connection; call <a href="xxfi_close.html">xxfi_close</a>. <br> 21990792Sgshapiro For a recipient-oriented routine, only fail for the current recipient; continue message processing. 22090792Sgshapiro </td> 22190792Sgshapiro </tr> 22290792Sgshapiro</table> 22390792Sgshapiro 22490792Sgshapiro<hr size="1"> 22590792Sgshapiro<font size="-1"> 226112810SgshapiroCopyright (c) 2000, 2003 Sendmail, Inc. and its suppliers. 22790792SgshapiroAll rights reserved. 22890792Sgshapiro<br> 22990792SgshapiroBy using this file, you agree to the terms and conditions set 230112810Sgshapiroforth in the LICENSE. 23190792Sgshapiro</font> 23290792Sgshapiro</body> 23390792Sgshapiro</html> 234