xref: /freebsd/contrib/sendmail/libmilter/docs/api.html (revision 5ef517c097100c80269c8a0e02678a89fde6b35e)
140266059SGregory Neil Shapiro<html>
240266059SGregory Neil Shapiro<head><title>Milter API</title></head>
340266059SGregory Neil Shapiro<body>
440266059SGregory Neil Shapiro<h1>Milter API</h1>
540266059SGregory Neil Shapiro
640266059SGregory Neil Shapiro<h2>Contents</h2>
740266059SGregory Neil Shapiro<ul>
840266059SGregory Neil Shapiro    <li>Library Control Functions
940266059SGregory Neil Shapiro    <li>Data Access Functions
1040266059SGregory Neil Shapiro    <li>Message Modification Functions
1140266059SGregory Neil Shapiro    <li>Callbacks
1240266059SGregory Neil Shapiro</ul>
1340266059SGregory Neil Shapiro
1440266059SGregory Neil Shapiro<h2>Library Control Functions</h2>
1540266059SGregory Neil Shapiro
1640266059SGregory Neil ShapiroBefore handing control to libmilter (by calling <a
1740266059SGregory Neil Shapirohref="smfi_main.html">smfi_main</a>), a filter may call the following
1840266059SGregory Neil Shapirofunctions to set libmilter parameters.  In particular, the filter must
1940266059SGregory Neil Shapirocall <a href="smfi_register.html">smfi_register</a> to register its
2040266059SGregory Neil Shapirocallbacks.  Each function will return either MI_SUCCESS or MI_FAILURE to
2140266059SGregory Neil Shapiroindicate the status of the operation.
2240266059SGregory Neil Shapiro<p>
2340266059SGregory Neil ShapiroNone of these functions communicate with the MTA.  All alter the
2440266059SGregory Neil Shapirolibrary's state, some of which is communicated to the MTA inside <a
2540266059SGregory Neil Shapirohref="smfi_main.html">smfi_main</a>.
2640266059SGregory Neil Shapiro<p>
2740266059SGregory Neil Shapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr>
2840266059SGregory Neil Shapiro
2940266059SGregory Neil Shapiro<tr><td><a href="smfi_register.html">smfi_register</a></td><td>Register a filter.</td></tr>
3040266059SGregory Neil Shapiro
3140266059SGregory Neil Shapiro<tr><td><a href="smfi_setconn.html">smfi_setconn</a></td><td>Specify socket to use.</td></tr>
3240266059SGregory Neil Shapiro
3340266059SGregory Neil Shapiro<tr><td><a href="smfi_settimeout.html">smfi_settimeout</a></td><td>Set timeout.</td></tr>
3440266059SGregory Neil Shapiro
3540266059SGregory Neil Shapiro<tr><td><a href="smfi_main.html">smfi_main</a></td><td>Hand control to libmilter.</td></tr>
3640266059SGregory Neil Shapiro
3740266059SGregory Neil Shapiro</table>
3840266059SGregory Neil Shapiro
3940266059SGregory Neil Shapiro<h2>Data Access Functions</h2>
4040266059SGregory Neil Shapiro
4140266059SGregory Neil ShapiroThe following functions may be called from within the filter-defined callbacks
4240266059SGregory Neil Shapiroto access information about the current connection or message.
4340266059SGregory Neil Shapiro<p>
4440266059SGregory Neil Shapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr>
4540266059SGregory Neil Shapiro<tr><td><a href="smfi_getsymval.html">smfi_getsymval</a></td><td>Return the value
4640266059SGregory Neil Shapiroof a symbol.</td></tr>
4740266059SGregory Neil Shapiro
4840266059SGregory Neil Shapiro<tr><td><a href="smfi_getpriv.html">smfi_getpriv</a></td><td>Get the private data
4940266059SGregory Neil Shapiropointer.</td></tr>
5040266059SGregory Neil Shapiro
5140266059SGregory Neil Shapiro<tr><td><a href="smfi_setpriv.html">smfi_setpriv</a></td><td>Set the private data
5240266059SGregory Neil Shapiropointer.</td></tr>
5340266059SGregory Neil Shapiro
5440266059SGregory Neil Shapiro<tr><td><a href="smfi_setreply.html">smfi_setreply</a></td><td>Set the specific
5540266059SGregory Neil Shapiroreply code to be used.</td></tr>
5640266059SGregory Neil Shapiro
5740266059SGregory Neil Shapiro</table>
5840266059SGregory Neil Shapiro
5940266059SGregory Neil Shapiro<h2>Message Modification Functions</h2>
6040266059SGregory Neil Shapiro
6140266059SGregory Neil ShapiroThe following functions change a message's contents and attributes.
6240266059SGregory Neil Shapiro<b>They may only be called in <a href="xxfi_eom.html">xxfi_eom</a></b>.
6340266059SGregory Neil ShapiroAll of these functions may invoke additional communication with the MTA.
6440266059SGregory Neil ShapiroThey will return either MI_SUCCESS or MI_FAILURE to indicate the status of
6540266059SGregory Neil Shapirothe operation.
6640266059SGregory Neil Shapiro
6740266059SGregory Neil Shapiro<p>
6840266059SGregory Neil ShapiroA filter must have set the appropriate flag (listed below) in the
6940266059SGregory Neil Shapirodescription passed to <a href="smfi_register.html">smfi_register</a>
7040266059SGregory Neil Shapiroto call any message modification function.  Failure to do so will
7140266059SGregory Neil Shapirocause the MTA to treat a call to the function as a failure of the
7240266059SGregory Neil Shapirofilter, terminating its connection.
7340266059SGregory Neil Shapiro
7440266059SGregory Neil Shapiro<p>
7540266059SGregory Neil ShapiroNote that the status returned indicates only whether or not the
7640266059SGregory Neil Shapirofilter's message was successfully sent to the MTA, not whether or not
7740266059SGregory Neil Shapirothe MTA performed the requested operation.  For example, <a
7840266059SGregory Neil Shapirohref="smfi_addheader.html">smfi_addheader</a>, when called with an
7940266059SGregory Neil Shapiroillegal header name, will return MI_SUCCESS even though the MTA may
8040266059SGregory Neil Shapirolater refuse to add the illegal header.
8140266059SGregory Neil Shapiro<p>
8240266059SGregory Neil Shapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th><th>SMFIF_* flag</tr>
8340266059SGregory Neil Shapiro<tr><td><a href="smfi_addheader.html">smfi_addheader</a></td><td>Add a header to
8440266059SGregory Neil Shapirothe message.</td><td>SMFIF_ADDHDRS</td></tr>
8540266059SGregory Neil Shapiro
8640266059SGregory 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>
8740266059SGregory Neil Shapiro
8840266059SGregory Neil Shapiro<tr><td><a href="smfi_addrcpt.html">smfi_addrcpt</a></td><td>Add a recipient to
8940266059SGregory Neil Shapirothe envelope.</td><td>SMFIF_ADDRCPT</td></tr>
9040266059SGregory Neil Shapiro
9140266059SGregory Neil Shapiro<tr><td><a href="smfi_delrcpt.html">smfi_delrcpt</a></td><td>Delete a recipient
9240266059SGregory Neil Shapirofrom the envelope.</td><td>SMFIF_DELRCPT</td></tr>
9340266059SGregory Neil Shapiro
9440266059SGregory Neil Shapiro<tr><td><a href="smfi_replacebody.html">smfi_replacebody</a></td><td>Replace the
9540266059SGregory Neil Shapirobody of the message.</td><td>SMFIF_CHGBODY</td></tr>
9640266059SGregory Neil Shapiro
9740266059SGregory Neil Shapiro</table>
9840266059SGregory Neil Shapiro
9940266059SGregory Neil Shapiro<h2>Callbacks</h2>
10040266059SGregory Neil Shapiro
10140266059SGregory Neil ShapiroThe filter should implement one or more of the following callbacks,
10240266059SGregory Neil Shapirowhich are registered via <a href="smfi_register.html">smfi_register</a>:
10340266059SGregory Neil Shapiro<p>
10440266059SGregory Neil Shapiro<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr>
10540266059SGregory Neil Shapiro
10640266059SGregory Neil Shapiro<tr><td><a href="xxfi_connect.html">xxfi_connect</a></td><td>connection info</td></tr>
10740266059SGregory Neil Shapiro
10840266059SGregory Neil Shapiro<tr><td><a href="xxfi_helo.html">xxfi_helo</a></td><td>SMTP HELO/EHLO command</td></tr>
10940266059SGregory Neil Shapiro
11040266059SGregory Neil Shapiro<tr><td><a href="xxfi_envfrom.html">xxfi_envfrom</a></td><td>envelope sender</td></tr>
11140266059SGregory Neil Shapiro
11240266059SGregory Neil Shapiro<tr><td><a href="xxfi_envrcpt.html">xxfi_envrcpt</a></td><td>envelope recipient</td></tr>
11340266059SGregory Neil Shapiro
11440266059SGregory Neil Shapiro<tr><td><a href="xxfi_header.html">xxfi_header</a></td><td>header</td></tr>
11540266059SGregory Neil Shapiro
11640266059SGregory Neil Shapiro<tr><td><a href="xxfi_eoh.html">xxfi_eoh</a></td><td>end of header</td></tr>
11740266059SGregory Neil Shapiro
11840266059SGregory Neil Shapiro<tr><td><a href="xxfi_body.html">xxfi_body</a></td><td>body block</td></tr>
11940266059SGregory Neil Shapiro
12040266059SGregory Neil Shapiro<tr><td><a href="xxfi_eom.html">xxfi_eom</a></td><td>end of message</td></tr>
12140266059SGregory Neil Shapiro
12240266059SGregory Neil Shapiro<tr><td><a href="xxfi_abort.html">xxfi_abort</a></td><td>message aborted</td></tr>
12340266059SGregory Neil Shapiro
12440266059SGregory Neil Shapiro<tr><td><a href="xxfi_close.html">xxfi_close</a></td><td>connection cleanup</td></tr>
12540266059SGregory Neil Shapiro
12640266059SGregory Neil Shapiro</table>
12740266059SGregory Neil Shapiro
12840266059SGregory Neil Shapiro<p>
12940266059SGregory Neil ShapiroThe above callbacks should all return one of the following return values,
13040266059SGregory Neil Shapirohaving the indicated meanings.  Any return other than one of the below
13140266059SGregory Neil Shapirovalues constitutes an error, and will cause sendmail to terminate its
13240266059SGregory Neil Shapiroconnection to the offending filter.
13340266059SGregory Neil Shapiro
13440266059SGregory Neil Shapiro<p><a name="conn-spec"></a>Milter distinguishes between recipient-,
13540266059SGregory Neil Shapiromessage-, and connection-oriented routines.  Recipient-oriented
13640266059SGregory Neil Shapirocallbacks may affect the processing of a single message recipient;
13740266059SGregory Neil Shapiromessage-oriented callbacks, a single message; connection-oriented
13840266059SGregory Neil Shapirocallbacks, an entire connection (during which multiple messages may be
13940266059SGregory Neil Shapirodelivered to multiple sets of recipients).
14040266059SGregory Neil Shapiro<a href="xxfi_envrcpt.html">xxfi_envrcpt</a> is recipient-oriented.
14140266059SGregory Neil Shapiro<a href="xxfi_connect.html">xxfi_connect</a>,
14240266059SGregory Neil Shapiro<a href="xxfi_helo.html">xxfi_helo</a> and
14340266059SGregory Neil Shapiro<a href="xxfi_close.html">xxfi_close</a> are connection-oriented.  All
14440266059SGregory Neil Shapiroother callbacks are message-oriented.
14540266059SGregory Neil Shapiro
14640266059SGregory Neil Shapiro<p>
14740266059SGregory Neil Shapiro<table border="1" cellspacing=0 cellpadding=2>
14840266059SGregory Neil Shapiro  <tr bgcolor="#dddddd"><th>Return value</th><th>Description</th></tr>
14940266059SGregory Neil Shapiro  <tr valign="top">
15040266059SGregory Neil Shapiro     <td>SMFIS_CONTINUE</td>
15140266059SGregory Neil Shapiro     <td>Continue processing the current connection, message, or recipient.
15240266059SGregory Neil Shapiro     </td>
15340266059SGregory Neil Shapiro  </tr>
15440266059SGregory Neil Shapiro  <tr valign="top">
15540266059SGregory Neil Shapiro     <td>SMFIS_REJECT</td>
15640266059SGregory Neil Shapiro     <td>For a connection-oriented routine, reject this connection; call <a href="xxfi_close.html">xxfi_close</a>.<br>
15740266059SGregory Neil Shapiro        For a message-oriented routine (except
15840266059SGregory Neil Shapiro	<a href="xxfi_eom.html">xxfi_eom</a> or
15940266059SGregory Neil Shapiro        <a href="xxfi_abort.html">xxfi_abort</a>), reject this message.<br>
16040266059SGregory Neil Shapiro	For a recipient-oriented routine, reject the current recipient (but continue processing the current message).
16140266059SGregory Neil Shapiro     </td>
16240266059SGregory Neil Shapiro  </tr>
16340266059SGregory Neil Shapiro  <tr valign="top">
16440266059SGregory Neil Shapiro     <td>SMFIS_DISCARD</td>
16540266059SGregory Neil Shapiro     <td>For a message- or recipient-oriented routine, accept this message, but silently discard it.<br>
16640266059SGregory Neil Shapiro     SMFIS_DISCARD should not be returned by a connection-oriented routine.
16740266059SGregory Neil Shapiro     </td>
16840266059SGregory Neil Shapiro  </tr>
16940266059SGregory Neil Shapiro  <tr valign="top">
17040266059SGregory Neil Shapiro     <td>SMFIS_ACCEPT</td>
17140266059SGregory 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>
17240266059SGregory Neil Shapiro         For a message- or recipient-oriented routine, accept this message without further filtering.<br>
17340266059SGregory Neil Shapiro     </td>
17440266059SGregory Neil Shapiro  </tr>
17540266059SGregory Neil Shapiro  <tr valign="top">
17640266059SGregory Neil Shapiro     <td>SMFIS_TEMPFAIL</td>
17740266059SGregory Neil Shapiro     <td>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code.
17840266059SGregory Neil Shapiro	 For a message-oriented routine (except <a href="xxfi_envfrom.html">xxfi_envfrom</a>), fail for this message. <br>
17940266059SGregory Neil Shapiro	 For a connection-oriented routine, fail for this connection; call <a href="xxfi_close.html">xxfi_close</a>. <br>
18040266059SGregory Neil Shapiro	 For a recipient-oriented routine, only fail for the current recipient; continue message processing.
18140266059SGregory Neil Shapiro     </td>
18240266059SGregory Neil Shapiro  </tr>
18340266059SGregory Neil Shapiro</table>
18440266059SGregory Neil Shapiro
18540266059SGregory Neil Shapiro<hr size="1">
18640266059SGregory Neil Shapiro<font size="-1">
1875ef517c0SGregory Neil ShapiroCopyright (c) 2000, 2003 Sendmail, Inc. and its suppliers.
18840266059SGregory Neil ShapiroAll rights reserved.
18940266059SGregory Neil Shapiro<br>
19040266059SGregory Neil ShapiroBy using this file, you agree to the terms and conditions set
1915ef517c0SGregory Neil Shapiroforth in the LICENSE.
19240266059SGregory Neil Shapiro</font>
19340266059SGregory Neil Shapiro</body>
19440266059SGregory Neil Shapiro</html>
195