195 lines
7.8 KiB
HTML
195 lines
7.8 KiB
HTML
<html>
|
|
<head><title>Milter API</title></head>
|
|
<body>
|
|
<h1>Milter API</h1>
|
|
|
|
<h2>Contents</h2>
|
|
<ul>
|
|
<li>Library Control Functions
|
|
<li>Data Access Functions
|
|
<li>Message Modification Functions
|
|
<li>Callbacks
|
|
</ul>
|
|
|
|
<h2>Library Control Functions</h2>
|
|
|
|
Before handing control to libmilter (by calling <a
|
|
href="smfi_main.html">smfi_main</a>), a filter may call the following
|
|
functions to set libmilter parameters. In particular, the filter must
|
|
call <a href="smfi_register.html">smfi_register</a> to register its
|
|
callbacks. Each function will return either MI_SUCCESS or MI_FAILURE to
|
|
indicate the status of the operation.
|
|
<p>
|
|
None of these functions communicate with the MTA. All alter the
|
|
library's state, some of which is communicated to the MTA inside <a
|
|
href="smfi_main.html">smfi_main</a>.
|
|
<p>
|
|
<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr>
|
|
|
|
<tr><td><a href="smfi_register.html">smfi_register</a></td><td>Register a filter.</td></tr>
|
|
|
|
<tr><td><a href="smfi_setconn.html">smfi_setconn</a></td><td>Specify socket to use.</td></tr>
|
|
|
|
<tr><td><a href="smfi_settimeout.html">smfi_settimeout</a></td><td>Set timeout.</td></tr>
|
|
|
|
<tr><td><a href="smfi_main.html">smfi_main</a></td><td>Hand control to libmilter.</td></tr>
|
|
|
|
</table>
|
|
|
|
<h2>Data Access Functions</h2>
|
|
|
|
The following functions may be called from within the filter-defined callbacks
|
|
to access information about the current connection or message.
|
|
<p>
|
|
<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr>
|
|
<tr><td><a href="smfi_getsymval.html">smfi_getsymval</a></td><td>Return the value
|
|
of a symbol.</td></tr>
|
|
|
|
<tr><td><a href="smfi_getpriv.html">smfi_getpriv</a></td><td>Get the private data
|
|
pointer.</td></tr>
|
|
|
|
<tr><td><a href="smfi_setpriv.html">smfi_setpriv</a></td><td>Set the private data
|
|
pointer.</td></tr>
|
|
|
|
<tr><td><a href="smfi_setreply.html">smfi_setreply</a></td><td>Set the specific
|
|
reply code to be used.</td></tr>
|
|
|
|
</table>
|
|
|
|
<h2>Message Modification Functions</h2>
|
|
|
|
The following functions change a message's contents and attributes.
|
|
<b>They may only be called in <a href="xxfi_eom.html">xxfi_eom</a></b>.
|
|
All of these functions may invoke additional communication with the MTA.
|
|
They will return either MI_SUCCESS or MI_FAILURE to indicate the status of
|
|
the operation.
|
|
|
|
<p>
|
|
A filter must have set the appropriate flag (listed below) in the
|
|
description passed to <a href="smfi_register.html">smfi_register</a>
|
|
to call any message modification function. Failure to do so will
|
|
cause the MTA to treat a call to the function as a failure of the
|
|
filter, terminating its connection.
|
|
|
|
<p>
|
|
Note that the status returned indicates only whether or not the
|
|
filter's message was successfully sent to the MTA, not whether or not
|
|
the MTA performed the requested operation. For example, <a
|
|
href="smfi_addheader.html">smfi_addheader</a>, when called with an
|
|
illegal header name, will return MI_SUCCESS even though the MTA may
|
|
later refuse to add the illegal header.
|
|
<p>
|
|
<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th><th>SMFIF_* flag</tr>
|
|
<tr><td><a href="smfi_addheader.html">smfi_addheader</a></td><td>Add a header to
|
|
the message.</td><td>SMFIF_ADDHDRS</td></tr>
|
|
|
|
<tr><td><a href="smfi_chgheader.html">smfi_chgheader</a></td><td>Change or delete a header.</td><td>SMFIF_CHGHDRS</td></tr>
|
|
|
|
<tr><td><a href="smfi_addrcpt.html">smfi_addrcpt</a></td><td>Add a recipient to
|
|
the envelope.</td><td>SMFIF_ADDRCPT</td></tr>
|
|
|
|
<tr><td><a href="smfi_delrcpt.html">smfi_delrcpt</a></td><td>Delete a recipient
|
|
from the envelope.</td><td>SMFIF_DELRCPT</td></tr>
|
|
|
|
<tr><td><a href="smfi_replacebody.html">smfi_replacebody</a></td><td>Replace the
|
|
body of the message.</td><td>SMFIF_CHGBODY</td></tr>
|
|
|
|
</table>
|
|
|
|
<h2>Callbacks</h2>
|
|
|
|
The filter should implement one or more of the following callbacks,
|
|
which are registered via <a href="smfi_register.html">smfi_register</a>:
|
|
<p>
|
|
<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr>
|
|
|
|
<tr><td><a href="xxfi_connect.html">xxfi_connect</a></td><td>connection info</td></tr>
|
|
|
|
<tr><td><a href="xxfi_helo.html">xxfi_helo</a></td><td>SMTP HELO/EHLO command</td></tr>
|
|
|
|
<tr><td><a href="xxfi_envfrom.html">xxfi_envfrom</a></td><td>envelope sender</td></tr>
|
|
|
|
<tr><td><a href="xxfi_envrcpt.html">xxfi_envrcpt</a></td><td>envelope recipient</td></tr>
|
|
|
|
<tr><td><a href="xxfi_header.html">xxfi_header</a></td><td>header</td></tr>
|
|
|
|
<tr><td><a href="xxfi_eoh.html">xxfi_eoh</a></td><td>end of header</td></tr>
|
|
|
|
<tr><td><a href="xxfi_body.html">xxfi_body</a></td><td>body block</td></tr>
|
|
|
|
<tr><td><a href="xxfi_eom.html">xxfi_eom</a></td><td>end of message</td></tr>
|
|
|
|
<tr><td><a href="xxfi_abort.html">xxfi_abort</a></td><td>message aborted</td></tr>
|
|
|
|
<tr><td><a href="xxfi_close.html">xxfi_close</a></td><td>connection cleanup</td></tr>
|
|
|
|
</table>
|
|
|
|
<p>
|
|
The above callbacks should all return one of the following return values,
|
|
having the indicated meanings. Any return other than one of the below
|
|
values constitutes an error, and will cause sendmail to terminate its
|
|
connection to the offending filter.
|
|
|
|
<p><a name="conn-spec"></a>Milter distinguishes between recipient-,
|
|
message-, and connection-oriented routines. Recipient-oriented
|
|
callbacks may affect the processing of a single message recipient;
|
|
message-oriented callbacks, a single message; connection-oriented
|
|
callbacks, an entire connection (during which multiple messages may be
|
|
delivered to multiple sets of recipients).
|
|
<a href="xxfi_envrcpt.html">xxfi_envrcpt</a> is recipient-oriented.
|
|
<a href="xxfi_connect.html">xxfi_connect</a>,
|
|
<a href="xxfi_helo.html">xxfi_helo</a> and
|
|
<a href="xxfi_close.html">xxfi_close</a> are connection-oriented. All
|
|
other callbacks are message-oriented.
|
|
|
|
<p>
|
|
<table border="1" cellspacing=0 cellpadding=2>
|
|
<tr bgcolor="#dddddd"><th>Return value</th><th>Description</th></tr>
|
|
<tr valign="top">
|
|
<td>SMFIS_CONTINUE</td>
|
|
<td>Continue processing the current connection, message, or recipient.
|
|
</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td>SMFIS_REJECT</td>
|
|
<td>For a connection-oriented routine, reject this connection; call <a href="xxfi_close.html">xxfi_close</a>.<br>
|
|
For a message-oriented routine (except
|
|
<a href="xxfi_eom.html">xxfi_eom</a> or
|
|
<a href="xxfi_abort.html">xxfi_abort</a>), reject this message.<br>
|
|
For a recipient-oriented routine, reject the current recipient (but continue processing the current message).
|
|
</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td>SMFIS_DISCARD</td>
|
|
<td>For a message- or recipient-oriented routine, accept this message, but silently discard it.<br>
|
|
SMFIS_DISCARD should not be returned by a connection-oriented routine.
|
|
</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td>SMFIS_ACCEPT</td>
|
|
<td>For a connection-oriented routine, accept this connection without further filter processing; call <a href="xxfi_close.html">xxfi_close</a>.<br>
|
|
For a message- or recipient-oriented routine, accept this message without further filtering.<br>
|
|
</td>
|
|
</tr>
|
|
<tr valign="top">
|
|
<td>SMFIS_TEMPFAIL</td>
|
|
<td>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code.
|
|
For a message-oriented routine (except <a href="xxfi_envfrom.html">xxfi_envfrom</a>), fail for this message. <br>
|
|
For a connection-oriented routine, fail for this connection; call <a href="xxfi_close.html">xxfi_close</a>. <br>
|
|
For a recipient-oriented routine, only fail for the current recipient; continue message processing.
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<hr size="1">
|
|
<font size="-1">
|
|
Copyright (c) 2000 Sendmail, Inc. and its suppliers.
|
|
All rights reserved.
|
|
<br>
|
|
By using this file, you agree to the terms and conditions set
|
|
forth in the <a href="LICENSE.txt">LICENSE</a>.
|
|
</font>
|
|
</body>
|
|
</html>
|