diff options
Diffstat (limited to 'contrib/sendmail/libmilter/docs/api.html')
| -rw-r--r-- | contrib/sendmail/libmilter/docs/api.html | 194 |
1 files changed, 194 insertions, 0 deletions
diff --git a/contrib/sendmail/libmilter/docs/api.html b/contrib/sendmail/libmilter/docs/api.html new file mode 100644 index 0000000..af714ef --- /dev/null +++ b/contrib/sendmail/libmilter/docs/api.html @@ -0,0 +1,194 @@ +<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> |
