diff options
Diffstat (limited to 'contrib/sendmail/libmilter/docs/api.html')
| -rw-r--r-- | contrib/sendmail/libmilter/docs/api.html | 369 |
1 files changed, 228 insertions, 141 deletions
diff --git a/contrib/sendmail/libmilter/docs/api.html b/contrib/sendmail/libmilter/docs/api.html index 23c4de4..4214df4 100644 --- a/contrib/sendmail/libmilter/docs/api.html +++ b/contrib/sendmail/libmilter/docs/api.html @@ -1,233 +1,320 @@ -<html> -<head><title>Milter API</title></head> -<body> +<HTML> +<HEAD><TITLE>Milter API</TITLE></HEAD> +<BODY> <!-- -$Id: api.html,v 1.18 2004/04/28 23:26:51 msk Exp $ +$Id: api.html,v 1.35 2006/11/30 23:09:23 ca Exp $ --> -<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 +<H1>Milter API</H1> + +<H2>Contents</H2> +<UL> + <LI><A HREF="#LibraryControlFunctions">Library Control Functions</A> + <LI><A HREF="#DataAccessFunctions">Data Access Functions</A> + <LI><A HREF="#MessageModificationFunctions">Message Modification Functions</A> + <LI><A HREF="#Callbacks">Callbacks</A> + <LI><A HREF="#Miscellaneous">Miscellaneous</A> +</UL> + +<H2><A NAME="LibraryControlFunctions">Library Control Functions</A></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> + +<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> +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_opensocket.html">smfi_opensocket</a></td><td>Try to create the interface socket.</td></tr> +<TR><TD><A HREF="smfi_opensocket.html">smfi_opensocket</A></TD><TD>Try to create the interface socket.</TD></TR> -<tr><td><a href="smfi_register.html">smfi_register</a></td><td>Register a filter.</td></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_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_settimeout.html">smfi_settimeout</A></TD><TD>Set timeout.</TD></TR> -<tr><td><a href="smfi_setbacklog.html">smfi_setbacklog</a></td><td>Define the incoming <i>listen</i>(2) queue size.</td></tr> +<TR><TD><A HREF="smfi_setbacklog.html">smfi_setbacklog</A></TD><TD>Define the incoming <CODE>listen(2)</CODE> queue size.</TD></TR> -<tr><td><a href="smfi_setdbg.html">smfi_setdbg</a></td><td>Set the milter library debugging (tracing) level.</td></tr> +<TR><TD><A HREF="smfi_setdbg.html">smfi_setdbg</A></TD><TD>Set the milter library debugging (tracing) level.</TD></TR> -<tr><td><a href="smfi_stop.html">smfi_stop</a></td><td>Cause an orderly shutdown.</td></tr> +<TR><TD><A HREF="smfi_stop.html">smfi_stop</A></TD><TD>Cause an orderly shutdown.</TD></TR> -<tr><td><a href="smfi_main.html">smfi_main</a></td><td>Hand control to libmilter.</td></tr> +<TR><TD><A HREF="smfi_main.html">smfi_main</A></TD><TD>Hand control to libmilter.</TD></TR> -</table> +</TABLE> -<h2>Data Access Functions</h2> +<H2><A NAME="DataAccessFunctions">Data Access Functions</A></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> +<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_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_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> +<TR><TD><A HREF="smfi_setreply.html">smfi_setreply</A></TD><TD>Set the specific +reply code to be used.</TD></TR> -<tr><td><a href="smfi_setmlreply.html">smfi_setmlreply</a></td><td>Set the -specific multi-line reply to be used.</td></tr> +<TR><TD><A HREF="smfi_setmlreply.html">smfi_setmlreply</A></TD><TD>Set the +specific multi-line reply to be used.</TD></TR> -</table> +</TABLE> -<h2>Message Modification Functions</h2> +<H2><A NAME="MessageModificationFunctions">Message Modification Functions</A></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>. +<EM>They may only be called in <A HREF="xxfi_eom.html">xxfi_eom</A></EM>. 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> +<P> A filter must have set the appropriate flag (listed below) in the -description passed to <a href="smfi_register.html">smfi_register</a> +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> +<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 +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> +<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_chgheader.html">smfi_chgheader</a></td><td>Change or delete a header.</td><td>SMFIF_CHGHDRS</td></tr> +<TR><TD><A HREF="smfi_insheader.html">smfi_insheader</A></TD><TD>Insert a +header into the message.</TD><TD>SMFIF_ADDHDRS</TD></TR> -<tr><td><a href="smfi_insheader.html">smfi_insheader</a></td><td>Insert a -header into the message.</td><td>SMFIF_ADDHDRS</td></tr> +<TR><TD><A HREF="smfi_chgfrom.html">smfi_chgfrom</A></TD><TD>Change the +envelope sender address.</TD><TD>SMFIF_CHGFROM</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_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_addrcpt_par.html">smfi_addrcpt_par</A></TD><TD>Add +a recipient including ESMTP parameter to the envelope. +</TD><TD>SMFIF_ADDRCPT_PAR</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> +<TR><TD><A HREF="smfi_delrcpt.html">smfi_delrcpt</A></TD><TD>Delete a recipient +from the envelope.</TD><TD>SMFIF_DELRCPT</TD></TR> -</table> +<TR><TD><A HREF="smfi_replacebody.html">smfi_replacebody</A></TD><TD>Replace the +body of the message.</TD><TD>SMFIF_CHGBODY</TD></TR> -<h2>Other Message Handling Functions</h2> +</TABLE> + +<H2>Other Message Handling Functions</H2> The following functions provide special case handling instructions for milter or the MTA, without altering the content or status of the message. -<b>They too may only be called in <a href="xxfi_eom.html">xxfi_eom</a></b>. +<EM>They too may only be called in <A HREF="xxfi_eom.html">xxfi_eom</A></EM>. 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> +<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. -<p> -<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr> -<tr><td><a href="smfi_progress.html">smfi_progress</a></td><td>Report operation in progress.</td></tr> +<P> +<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> +<TR><TD><A HREF="smfi_progress.html">smfi_progress</A></TD><TD>Report operation in progress.</TD></TR> -<tr><td><a href="smfi_quarantine.html">smfi_quarantine</a></td><td>Quarantine a message.</td></tr> +<TR><TD><A HREF="smfi_quarantine.html">smfi_quarantine</A></TD><TD>Quarantine a message.</TD></TR> -</table> +</TABLE> -<h2><a name="callbacks">Callbacks</a></h2> +<H2><A NAME="Callbacks">Callbacks</A></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> +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_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_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_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_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_data.html">xxfi_data</A></TD><TD>DATA command</TD></TR> -<tr><td><a href="xxfi_eoh.html">xxfi_eoh</a></td><td>end of header</td></tr> +<TR><TD><A HREF="xxfi_unknown.html">xxfi_unknown</A></TD><TD>Unknown SMTP command</TD></TR> -<tr><td><a href="xxfi_body.html">xxfi_body</a></td><td>body block</td></tr> +<TR><TD><A HREF="xxfi_header.html">xxfi_header</A></TD><TD>header</TD></TR> -<tr><td><a href="xxfi_eom.html">xxfi_eom</a></td><td>end of message</td></tr> +<TR><TD><A HREF="xxfi_eoh.html">xxfi_eoh</A></TD><TD>end of header</TD></TR> -<tr><td><a href="xxfi_abort.html">xxfi_abort</a></td><td>message aborted</td></tr> +<TR><TD><A HREF="xxfi_body.html">xxfi_body</A></TD><TD>body block</TD></TR> -<tr><td><a href="xxfi_close.html">xxfi_close</a></td><td>connection cleanup</td></tr> +<TR><TD><A HREF="xxfi_eom.html">xxfi_eom</A></TD><TD>end of message</TD></TR> -</table> +<TR><TD><A HREF="xxfi_abort.html">xxfi_abort</A></TD><TD>message aborted</TD></TR> -<p> +<TR><TD><A HREF="xxfi_close.html">xxfi_close</A></TD><TD>connection cleanup</TD></TR> + +<TR><TD><A HREF="xxfi_negotiate.html">xxfi_negotiate</A></TD><TD>option negotiattion</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">Milter</a> distinguishes between recipient-, +<P><A NAME="conn-spec">Milter</A> 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 +<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> +<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> + <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> + </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> + </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, 2003 Sendmail, Inc. and its suppliers. + </TD> + </TR> + + <TR valign="top"> + <TD><A NAME="SMFIS_SKIP">SMFIS_SKIP</A></TD> + <TD>Skip further callbacks of the same type in this transaction. + Currently this return value is only allowed in + <A HREF="xxfi_body.html">xxfi_body()</A>. + It can be used if a milter has received sufficiently many + body chunks to make a decision, but still wants to invoke + message modification functions that are only allowed to be called from + <A HREF="xxfi_eom.html">xxfi_eom()</A>. + Note: the milter <EM>must</EM> + <A HREF="xxfi_negotiate.html">negotiate</A> + this behavior with the MTA, i.e., it must check whether + the protocol action + <A HREF="xxfi_negotiate.html#SMFIP_SKIP"><CODE>SMFIP_SKIP</CODE></A> + is available and if so, the milter must request it. + </TD> + </TR> + + <TR valign="top"> + <TD><A NAME="SMFIS_NOREPLY">SMFIS_NOREPLY</A></TD> + <TD>Do not send a reply back to the MTA. + The milter <EM>must</EM> + <A HREF="xxfi_negotiate.html">negotiate</A> + this behavior with the MTA, i.e., it must check whether + the appropriate protocol action + <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> + is available and if so, the milter must request it. + If you set the + <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> + protocol action for a callback, that callback <EM>must</EM> + always reply with + SMFIS_NOREPLY. + Using any other reply code is a violation of the API. + If in some cases your callback may return another value + (e.g., due to some resource shortages), then you + <EM>must not</EM> set + <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> + and you must use + SMFIS_CONTINUE as the default return code. + (Alternatively you can try to delay reporting the problem to + a later callback for which + <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> + is not set.) + </TD> + </TR> + +</TABLE> + +<H2><A NAME="Miscellaneous">Miscellaneous</A></H2> + +<P> +<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR> + +<TR><TD><A HREF="smfi_version.html">smfi_version</A></TD><TD>libmilter (runtime) version info</TD></TR> + +<TR><TD><A HREF="smfi_setsymlist.html">smfi_setsymlist</A></TD><TD> +Set the list of macros that the milter wants to receive from the MTA +for a protocol stage. +</TD></TR> + +</TABLE> + +<P> +<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Constant</TH><TH>Description</TH></TR> + +<TR><TD><A HREF="smfi_version.html">SMFI_VERSION</A></TD><TD>libmilter (compile time) version info</TD></TR> + +</TABLE> + + +<HR SIZE="1"> +<FONT SIZE="-1"> +Copyright (c) 2000, 2003, 2006 Sendmail, Inc. and its suppliers. All rights reserved. -<br> +<BR> By using this file, you agree to the terms and conditions set forth in the LICENSE. -</font> -</body> -</html> +</FONT> +</BODY> +</HTML> |
