140266059SGregory Neil Shapiro<html> 240266059SGregory Neil Shapiro<head><title>Milter API</title></head> 340266059SGregory Neil Shapiro<body> 4e92d3f3fSGregory Neil Shapiro<!-- 5e92d3f3fSGregory Neil Shapiro$Id: api.html,v 1.18 2004/04/28 23:26:51 msk Exp $ 6e92d3f3fSGregory Neil Shapiro--> 740266059SGregory Neil Shapiro<h1>Milter API</h1> 840266059SGregory Neil Shapiro 940266059SGregory Neil Shapiro<h2>Contents</h2> 1040266059SGregory Neil Shapiro<ul> 1140266059SGregory Neil Shapiro <li>Library Control Functions 1240266059SGregory Neil Shapiro <li>Data Access Functions 1340266059SGregory Neil Shapiro <li>Message Modification Functions 1440266059SGregory Neil Shapiro <li>Callbacks 1540266059SGregory Neil Shapiro</ul> 1640266059SGregory Neil Shapiro 1740266059SGregory Neil Shapiro<h2>Library Control Functions</h2> 1840266059SGregory Neil Shapiro 1940266059SGregory Neil ShapiroBefore handing control to libmilter (by calling <a 2040266059SGregory Neil Shapirohref="smfi_main.html">smfi_main</a>), a filter may call the following 2140266059SGregory Neil Shapirofunctions to set libmilter parameters. In particular, the filter must 2240266059SGregory Neil Shapirocall <a href="smfi_register.html">smfi_register</a> to register its 2340266059SGregory Neil Shapirocallbacks. Each function will return either MI_SUCCESS or MI_FAILURE to 2440266059SGregory Neil Shapiroindicate the status of the operation. 2540266059SGregory Neil Shapiro<p> 2640266059SGregory Neil ShapiroNone of these functions communicate with the MTA. All alter the 2740266059SGregory Neil Shapirolibrary's state, some of which is communicated to the MTA inside <a 2840266059SGregory Neil Shapirohref="smfi_main.html">smfi_main</a>. 2940266059SGregory Neil Shapiro<p> 3040266059SGregory Neil Shapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 3140266059SGregory Neil Shapiro 32e92d3f3fSGregory Neil Shapiro<tr><td><a href="smfi_opensocket.html">smfi_opensocket</a></td><td>Try to create the interface socket.</td></tr> 33e92d3f3fSGregory Neil Shapiro 3440266059SGregory Neil Shapiro<tr><td><a href="smfi_register.html">smfi_register</a></td><td>Register a filter.</td></tr> 3540266059SGregory Neil Shapiro 3640266059SGregory Neil Shapiro<tr><td><a href="smfi_setconn.html">smfi_setconn</a></td><td>Specify socket to use.</td></tr> 3740266059SGregory Neil Shapiro 3840266059SGregory Neil Shapiro<tr><td><a href="smfi_settimeout.html">smfi_settimeout</a></td><td>Set timeout.</td></tr> 3940266059SGregory Neil Shapiro 40e92d3f3fSGregory Neil Shapiro<tr><td><a href="smfi_setbacklog.html">smfi_setbacklog</a></td><td>Define the incoming <i>listen</i>(2) queue size.</td></tr> 41e92d3f3fSGregory Neil Shapiro 42e92d3f3fSGregory Neil Shapiro<tr><td><a href="smfi_setdbg.html">smfi_setdbg</a></td><td>Set the milter library debugging (tracing) level.</td></tr> 43e92d3f3fSGregory Neil Shapiro 44e92d3f3fSGregory Neil Shapiro<tr><td><a href="smfi_stop.html">smfi_stop</a></td><td>Cause an orderly shutdown.</td></tr> 45e92d3f3fSGregory Neil Shapiro 4640266059SGregory Neil Shapiro<tr><td><a href="smfi_main.html">smfi_main</a></td><td>Hand control to libmilter.</td></tr> 4740266059SGregory Neil Shapiro 4840266059SGregory Neil Shapiro</table> 4940266059SGregory Neil Shapiro 5040266059SGregory Neil Shapiro<h2>Data Access Functions</h2> 5140266059SGregory Neil Shapiro 5240266059SGregory Neil ShapiroThe following functions may be called from within the filter-defined callbacks 5340266059SGregory Neil Shapiroto access information about the current connection or message. 5440266059SGregory Neil Shapiro<p> 5540266059SGregory Neil Shapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 5640266059SGregory Neil Shapiro<tr><td><a href="smfi_getsymval.html">smfi_getsymval</a></td><td>Return the value 5740266059SGregory Neil Shapiroof a symbol.</td></tr> 5840266059SGregory Neil Shapiro 5940266059SGregory Neil Shapiro<tr><td><a href="smfi_getpriv.html">smfi_getpriv</a></td><td>Get the private data 6040266059SGregory Neil Shapiropointer.</td></tr> 6140266059SGregory Neil Shapiro 6240266059SGregory Neil Shapiro<tr><td><a href="smfi_setpriv.html">smfi_setpriv</a></td><td>Set the private data 6340266059SGregory Neil Shapiropointer.</td></tr> 6440266059SGregory Neil Shapiro 6540266059SGregory Neil Shapiro<tr><td><a href="smfi_setreply.html">smfi_setreply</a></td><td>Set the specific 6640266059SGregory Neil Shapiroreply code to be used.</td></tr> 6740266059SGregory Neil Shapiro 68e92d3f3fSGregory Neil Shapiro<tr><td><a href="smfi_setmlreply.html">smfi_setmlreply</a></td><td>Set the 69e92d3f3fSGregory Neil Shapirospecific multi-line reply to be used.</td></tr> 70e92d3f3fSGregory Neil Shapiro 7140266059SGregory Neil Shapiro</table> 7240266059SGregory Neil Shapiro 7340266059SGregory Neil Shapiro<h2>Message Modification Functions</h2> 7440266059SGregory Neil Shapiro 7540266059SGregory Neil ShapiroThe following functions change a message's contents and attributes. 7640266059SGregory Neil Shapiro<b>They may only be called in <a href="xxfi_eom.html">xxfi_eom</a></b>. 7740266059SGregory Neil ShapiroAll of these functions may invoke additional communication with the MTA. 7840266059SGregory Neil ShapiroThey will return either MI_SUCCESS or MI_FAILURE to indicate the status of 7940266059SGregory Neil Shapirothe operation. 8040266059SGregory Neil Shapiro 8140266059SGregory Neil Shapiro<p> 8240266059SGregory Neil ShapiroA filter must have set the appropriate flag (listed below) in the 8340266059SGregory Neil Shapirodescription passed to <a href="smfi_register.html">smfi_register</a> 8440266059SGregory Neil Shapiroto call any message modification function. Failure to do so will 8540266059SGregory Neil Shapirocause the MTA to treat a call to the function as a failure of the 8640266059SGregory Neil Shapirofilter, terminating its connection. 8740266059SGregory Neil Shapiro 8840266059SGregory Neil Shapiro<p> 8940266059SGregory Neil ShapiroNote that the status returned indicates only whether or not the 9040266059SGregory Neil Shapirofilter's message was successfully sent to the MTA, not whether or not 9140266059SGregory Neil Shapirothe MTA performed the requested operation. For example, <a 9240266059SGregory Neil Shapirohref="smfi_addheader.html">smfi_addheader</a>, when called with an 9340266059SGregory Neil Shapiroillegal header name, will return MI_SUCCESS even though the MTA may 9440266059SGregory Neil Shapirolater refuse to add the illegal header. 9540266059SGregory Neil Shapiro<p> 9640266059SGregory Neil Shapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th><th>SMFIF_* flag</tr> 9740266059SGregory Neil Shapiro<tr><td><a href="smfi_addheader.html">smfi_addheader</a></td><td>Add a header to 9840266059SGregory Neil Shapirothe message.</td><td>SMFIF_ADDHDRS</td></tr> 9940266059SGregory Neil Shapiro 10040266059SGregory Neil Shapiro<tr><td><a href="smfi_chgheader.html">smfi_chgheader</a></td><td>Change or delete a header.</td><td>SMFIF_CHGHDRS</td></tr> 10140266059SGregory Neil Shapiro 102e92d3f3fSGregory Neil Shapiro<tr><td><a href="smfi_insheader.html">smfi_insheader</a></td><td>Insert a 103e92d3f3fSGregory Neil Shapiroheader into the message.</td><td>SMFIF_ADDHDRS</td></tr> 104e92d3f3fSGregory Neil Shapiro 10540266059SGregory Neil Shapiro<tr><td><a href="smfi_addrcpt.html">smfi_addrcpt</a></td><td>Add a recipient to 10640266059SGregory Neil Shapirothe envelope.</td><td>SMFIF_ADDRCPT</td></tr> 10740266059SGregory Neil Shapiro 10840266059SGregory Neil Shapiro<tr><td><a href="smfi_delrcpt.html">smfi_delrcpt</a></td><td>Delete a recipient 10940266059SGregory Neil Shapirofrom the envelope.</td><td>SMFIF_DELRCPT</td></tr> 11040266059SGregory Neil Shapiro 11140266059SGregory Neil Shapiro<tr><td><a href="smfi_replacebody.html">smfi_replacebody</a></td><td>Replace the 11240266059SGregory Neil Shapirobody of the message.</td><td>SMFIF_CHGBODY</td></tr> 11340266059SGregory Neil Shapiro 11440266059SGregory Neil Shapiro</table> 11540266059SGregory Neil Shapiro 116e92d3f3fSGregory Neil Shapiro<h2>Other Message Handling Functions</h2> 117e92d3f3fSGregory Neil Shapiro 118e92d3f3fSGregory Neil ShapiroThe following functions provide special case handling instructions for 119e92d3f3fSGregory Neil Shapiromilter or the MTA, without altering the content or status of the message. 120e92d3f3fSGregory Neil Shapiro<b>They too may only be called in <a href="xxfi_eom.html">xxfi_eom</a></b>. 121e92d3f3fSGregory Neil ShapiroAll of these functions may invoke additional communication with the MTA. 122e92d3f3fSGregory Neil ShapiroThey will return either MI_SUCCESS or MI_FAILURE to indicate the status of 123e92d3f3fSGregory Neil Shapirothe operation. 124e92d3f3fSGregory Neil Shapiro 125e92d3f3fSGregory Neil Shapiro<p> 126e92d3f3fSGregory Neil ShapiroNote that the status returned indicates only whether or not the 127e92d3f3fSGregory Neil Shapirofilter's message was successfully sent to the MTA, not whether or not 128e92d3f3fSGregory Neil Shapirothe MTA performed the requested operation. 129e92d3f3fSGregory Neil Shapiro 130e92d3f3fSGregory Neil Shapiro<p> 131e92d3f3fSGregory Neil Shapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 132e92d3f3fSGregory Neil Shapiro<tr><td><a href="smfi_progress.html">smfi_progress</a></td><td>Report operation in progress.</td></tr> 133e92d3f3fSGregory Neil Shapiro 134e92d3f3fSGregory Neil Shapiro<tr><td><a href="smfi_quarantine.html">smfi_quarantine</a></td><td>Quarantine a message.</td></tr> 135e92d3f3fSGregory Neil Shapiro 136e92d3f3fSGregory Neil Shapiro</table> 137e92d3f3fSGregory Neil Shapiro 138e92d3f3fSGregory Neil Shapiro<h2><a name="callbacks">Callbacks</a></h2> 13940266059SGregory Neil Shapiro 14040266059SGregory Neil ShapiroThe filter should implement one or more of the following callbacks, 14140266059SGregory Neil Shapirowhich are registered via <a href="smfi_register.html">smfi_register</a>: 14240266059SGregory Neil Shapiro<p> 14340266059SGregory Neil Shapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> 14440266059SGregory Neil Shapiro 14540266059SGregory Neil Shapiro<tr><td><a href="xxfi_connect.html">xxfi_connect</a></td><td>connection info</td></tr> 14640266059SGregory Neil Shapiro 14740266059SGregory Neil Shapiro<tr><td><a href="xxfi_helo.html">xxfi_helo</a></td><td>SMTP HELO/EHLO command</td></tr> 14840266059SGregory Neil Shapiro 14940266059SGregory Neil Shapiro<tr><td><a href="xxfi_envfrom.html">xxfi_envfrom</a></td><td>envelope sender</td></tr> 15040266059SGregory Neil Shapiro 15140266059SGregory Neil Shapiro<tr><td><a href="xxfi_envrcpt.html">xxfi_envrcpt</a></td><td>envelope recipient</td></tr> 15240266059SGregory Neil Shapiro 15340266059SGregory Neil Shapiro<tr><td><a href="xxfi_header.html">xxfi_header</a></td><td>header</td></tr> 15440266059SGregory Neil Shapiro 15540266059SGregory Neil Shapiro<tr><td><a href="xxfi_eoh.html">xxfi_eoh</a></td><td>end of header</td></tr> 15640266059SGregory Neil Shapiro 15740266059SGregory Neil Shapiro<tr><td><a href="xxfi_body.html">xxfi_body</a></td><td>body block</td></tr> 15840266059SGregory Neil Shapiro 15940266059SGregory Neil Shapiro<tr><td><a href="xxfi_eom.html">xxfi_eom</a></td><td>end of message</td></tr> 16040266059SGregory Neil Shapiro 16140266059SGregory Neil Shapiro<tr><td><a href="xxfi_abort.html">xxfi_abort</a></td><td>message aborted</td></tr> 16240266059SGregory Neil Shapiro 16340266059SGregory Neil Shapiro<tr><td><a href="xxfi_close.html">xxfi_close</a></td><td>connection cleanup</td></tr> 16440266059SGregory Neil Shapiro 16540266059SGregory Neil Shapiro</table> 16640266059SGregory Neil Shapiro 16740266059SGregory Neil Shapiro<p> 16840266059SGregory Neil ShapiroThe above callbacks should all return one of the following return values, 16940266059SGregory Neil Shapirohaving the indicated meanings. Any return other than one of the below 17040266059SGregory Neil Shapirovalues constitutes an error, and will cause sendmail to terminate its 17140266059SGregory Neil Shapiroconnection to the offending filter. 17240266059SGregory Neil Shapiro 173e92d3f3fSGregory Neil Shapiro<p><a name="conn-spec">Milter</a> distinguishes between recipient-, 17440266059SGregory Neil Shapiromessage-, and connection-oriented routines. Recipient-oriented 17540266059SGregory Neil Shapirocallbacks may affect the processing of a single message recipient; 17640266059SGregory Neil Shapiromessage-oriented callbacks, a single message; connection-oriented 17740266059SGregory Neil Shapirocallbacks, an entire connection (during which multiple messages may be 17840266059SGregory Neil Shapirodelivered to multiple sets of recipients). 17940266059SGregory Neil Shapiro<a href="xxfi_envrcpt.html">xxfi_envrcpt</a> is recipient-oriented. 18040266059SGregory Neil Shapiro<a href="xxfi_connect.html">xxfi_connect</a>, 18140266059SGregory Neil Shapiro<a href="xxfi_helo.html">xxfi_helo</a> and 18240266059SGregory Neil Shapiro<a href="xxfi_close.html">xxfi_close</a> are connection-oriented. All 18340266059SGregory Neil Shapiroother callbacks are message-oriented. 18440266059SGregory Neil Shapiro 18540266059SGregory Neil Shapiro<p> 18640266059SGregory Neil Shapiro<table border="1" cellspacing=0 cellpadding=2> 18740266059SGregory Neil Shapiro <tr bgcolor="#dddddd"><th>Return value</th><th>Description</th></tr> 18840266059SGregory Neil Shapiro <tr valign="top"> 18940266059SGregory Neil Shapiro <td>SMFIS_CONTINUE</td> 19040266059SGregory Neil Shapiro <td>Continue processing the current connection, message, or recipient. 19140266059SGregory Neil Shapiro </td> 19240266059SGregory Neil Shapiro </tr> 19340266059SGregory Neil Shapiro <tr valign="top"> 19440266059SGregory Neil Shapiro <td>SMFIS_REJECT</td> 19540266059SGregory Neil Shapiro <td>For a connection-oriented routine, reject this connection; call <a href="xxfi_close.html">xxfi_close</a>.<br> 19640266059SGregory Neil Shapiro For a message-oriented routine (except 19740266059SGregory Neil Shapiro <a href="xxfi_eom.html">xxfi_eom</a> or 19840266059SGregory Neil Shapiro <a href="xxfi_abort.html">xxfi_abort</a>), reject this message.<br> 19940266059SGregory Neil Shapiro For a recipient-oriented routine, reject the current recipient (but continue processing the current message). 20040266059SGregory Neil Shapiro </td> 20140266059SGregory Neil Shapiro </tr> 20240266059SGregory Neil Shapiro <tr valign="top"> 20340266059SGregory Neil Shapiro <td>SMFIS_DISCARD</td> 20440266059SGregory Neil Shapiro <td>For a message- or recipient-oriented routine, accept this message, but silently discard it.<br> 20540266059SGregory Neil Shapiro SMFIS_DISCARD should not be returned by a connection-oriented routine. 20640266059SGregory Neil Shapiro </td> 20740266059SGregory Neil Shapiro </tr> 20840266059SGregory Neil Shapiro <tr valign="top"> 20940266059SGregory Neil Shapiro <td>SMFIS_ACCEPT</td> 21040266059SGregory Neil Shapiro <td>For a connection-oriented routine, accept this connection without further filter processing; call <a href="xxfi_close.html">xxfi_close</a>.<br> 21140266059SGregory Neil Shapiro For a message- or recipient-oriented routine, accept this message without further filtering.<br> 21240266059SGregory Neil Shapiro </td> 21340266059SGregory Neil Shapiro </tr> 21440266059SGregory Neil Shapiro <tr valign="top"> 21540266059SGregory Neil Shapiro <td>SMFIS_TEMPFAIL</td> 21640266059SGregory Neil Shapiro <td>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code. 21740266059SGregory Neil Shapiro For a message-oriented routine (except <a href="xxfi_envfrom.html">xxfi_envfrom</a>), fail for this message. <br> 21840266059SGregory Neil Shapiro For a connection-oriented routine, fail for this connection; call <a href="xxfi_close.html">xxfi_close</a>. <br> 21940266059SGregory Neil Shapiro For a recipient-oriented routine, only fail for the current recipient; continue message processing. 22040266059SGregory Neil Shapiro </td> 22140266059SGregory Neil Shapiro </tr> 22240266059SGregory Neil Shapiro</table> 22340266059SGregory Neil Shapiro 22440266059SGregory Neil Shapiro<hr size="1"> 22540266059SGregory Neil Shapiro<font size="-1"> 2265ef517c0SGregory Neil ShapiroCopyright (c) 2000, 2003 Sendmail, Inc. and its suppliers. 22740266059SGregory Neil ShapiroAll rights reserved. 22840266059SGregory Neil Shapiro<br> 22940266059SGregory Neil ShapiroBy using this file, you agree to the terms and conditions set 2305ef517c0SGregory Neil Shapiroforth in the LICENSE. 23140266059SGregory Neil Shapiro</font> 23240266059SGregory Neil Shapiro</body> 23340266059SGregory Neil Shapiro</html> 234