contrib/sendmail-8.13.8/libmilter/docs/api.html

   1 <html>
   2 <head><title>Milter API</title></head>
   3 <body>
   4 <!--
   5 $Id: api.html,v 1.18 2004/04/28 23:26:51 msk Exp $
   6 -->
   7 <h1>Milter API</h1>
   8
   9 <h2>Contents</h2>
  10 <ul>
  11     <li>Library Control Functions
  12     <li>Data Access Functions
  13     <li>Message Modification Functions
  14     <li>Callbacks
  15 </ul>
  16
  17 <h2>Library Control Functions</h2>
  18
  19 Before handing control to libmilter (by calling <a
  20 href="smfi_main.html">smfi_main</a>), a filter may call the following
  21 functions to set libmilter parameters.  In particular, the filter must
  22 call <a href="smfi_register.html">smfi_register</a> to register its
  23 callbacks.  Each function will return either MI_SUCCESS or MI_FAILURE to
  24 indicate the status of the operation.
  25 <p>
  26 None of these functions communicate with the MTA.  All alter the
  27 library's state, some of which is communicated to the MTA inside <a
  28 href="smfi_main.html">smfi_main</a>.
  29 <p>
  30 <table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr>
  31
  32 <tr><td><a href="smfi_opensocket.html">smfi_opensocket</a></td><td>Try to create the interface socket.</td></tr>
  33
  34 <tr><td><a href="smfi_register.html">smfi_register</a></td><td>Register a filter.</td></tr>
  35
  36 <tr><td><a href="smfi_setconn.html">smfi_setconn</a></td><td>Specify socket to use.</td></tr>
  37
  38 <tr><td><a href="smfi_settimeout.html">smfi_settimeout</a></td><td>Set timeout.</td></tr>
  39
  40 <tr><td><a href="smfi_setbacklog.html">smfi_setbacklog</a></td><td>Define the incoming <i>listen</i>(2) queue size.</td></tr>
  41
  42 <tr><td><a href="smfi_setdbg.html">smfi_setdbg</a></td><td>Set the milter library debugging (tracing) level.</td></tr>
  43
  44 <tr><td><a href="smfi_stop.html">smfi_stop</a></td><td>Cause an orderly shutdown.</td></tr>
  45
  46 <tr><td><a href="smfi_main.html">smfi_main</a></td><td>Hand control to libmilter.</td></tr>
  47
  48 </table>
  49
  50 <h2>Data Access Functions</h2>
  51
  52 The following functions may be called from within the filter-defined callbacks
  53 to access information about the current connection or message.
  54 <p>
  55 <table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr>
  56 <tr><td><a href="smfi_getsymval.html">smfi_getsymval</a></td><td>Return the value
  57 of a symbol.</td></tr>
  58
  59 <tr><td><a href="smfi_getpriv.html">smfi_getpriv</a></td><td>Get the private data
  60 pointer.</td></tr>
  61
  62 <tr><td><a href="smfi_setpriv.html">smfi_setpriv</a></td><td>Set the private data
  63 pointer.</td></tr>
  64
  65 <tr><td><a href="smfi_setreply.html">smfi_setreply</a></td><td>Set the specific
  66 reply code to be used.</td></tr>
  67
  68 <tr><td><a href="smfi_setmlreply.html">smfi_setmlreply</a></td><td>Set the
  69 specific multi-line reply to be used.</td></tr>
  70
  71 </table>
  72
  73 <h2>Message Modification Functions</h2>
  74
  75 The following functions change a message's contents and attributes.
  76 <b>They may only be called in <a href="xxfi_eom.html">xxfi_eom</a></b>.
  77 All of these functions may invoke additional communication with the MTA.
  78 They will return either MI_SUCCESS or MI_FAILURE to indicate the status of
  79 the operation.
  80
  81 <p>
  82 A filter must have set the appropriate flag (listed below) in the
  83 description passed to <a href="smfi_register.html">smfi_register</a>
  84 to call any message modification function.  Failure to do so will
  85 cause the MTA to treat a call to the function as a failure of the
  86 filter, terminating its connection.
  87
  88 <p>
  89 Note that the status returned indicates only whether or not the
  90 filter's message was successfully sent to the MTA, not whether or not
  91 the MTA performed the requested operation.  For example, <a
  92 href="smfi_addheader.html">smfi_addheader</a>, when called with an
  93 illegal header name, will return MI_SUCCESS even though the MTA may
  94 later refuse to add the illegal header.
  95 <p>
  96 <table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th><th>SMFIF_* flag</tr>
  97 <tr><td><a href="smfi_addheader.html">smfi_addheader</a></td><td>Add a header to
  98 the message.</td><td>SMFIF_ADDHDRS</td></tr>
  99
 100 <tr><td><a href="smfi_chgheader.html">smfi_chgheader</a></td><td>Change or delete a header.</td><td>SMFIF_CHGHDRS</td></tr>
 101
 102 <tr><td><a href="smfi_insheader.html">smfi_insheader</a></td><td>Insert a
 103 header into the message.</td><td>SMFIF_ADDHDRS</td></tr>
 104
 105 <tr><td><a href="smfi_addrcpt.html">smfi_addrcpt</a></td><td>Add a recipient to
 106 the envelope.</td><td>SMFIF_ADDRCPT</td></tr>
 107
 108 <tr><td><a href="smfi_delrcpt.html">smfi_delrcpt</a></td><td>Delete a recipient
 109 from the envelope.</td><td>SMFIF_DELRCPT</td></tr>
 110
 111 <tr><td><a href="smfi_replacebody.html">smfi_replacebody</a></td><td>Replace the
 112 body of the message.</td><td>SMFIF_CHGBODY</td></tr>
 113
 114 </table>
 115
 116 <h2>Other Message Handling Functions</h2>
 117
 118 The following functions provide special case handling instructions for
 119 milter or the MTA, without altering the content or status of the message.
 120 <b>They too may only be called in <a href="xxfi_eom.html">xxfi_eom</a></b>.
 121 All of these functions may invoke additional communication with the MTA.
 122 They will return either MI_SUCCESS or MI_FAILURE to indicate the status of
 123 the operation.
 124
 125 <p>
 126 Note that the status returned indicates only whether or not the
 127 filter's message was successfully sent to the MTA, not whether or not
 128 the MTA performed the requested operation.
 129
 130 <p>
 131 <table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr>
 132 <tr><td><a href="smfi_progress.html">smfi_progress</a></td><td>Report operation in progress.</td></tr>
 133
 134 <tr><td><a href="smfi_quarantine.html">smfi_quarantine</a></td><td>Quarantine a message.</td></tr>
 135
 136 </table>
 137
 138 <h2><a name="callbacks">Callbacks</a></h2>
 139
 140 The filter should implement one or more of the following callbacks,
 141 which are registered via <a href="smfi_register.html">smfi_register</a>:
 142 <p>
 143 <table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr>
 144
 145 <tr><td><a href="xxfi_connect.html">xxfi_connect</a></td><td>connection info</td></tr>
 146
 147 <tr><td><a href="xxfi_helo.html">xxfi_helo</a></td><td>SMTP HELO/EHLO command</td></tr>
 148
 149 <tr><td><a href="xxfi_envfrom.html">xxfi_envfrom</a></td><td>envelope sender</td></tr>
 150
 151 <tr><td><a href="xxfi_envrcpt.html">xxfi_envrcpt</a></td><td>envelope recipient</td></tr>
 152
 153 <tr><td><a href="xxfi_header.html">xxfi_header</a></td><td>header</td></tr>
 154
 155 <tr><td><a href="xxfi_eoh.html">xxfi_eoh</a></td><td>end of header</td></tr>
 156
 157 <tr><td><a href="xxfi_body.html">xxfi_body</a></td><td>body block</td></tr>
 158
 159 <tr><td><a href="xxfi_eom.html">xxfi_eom</a></td><td>end of message</td></tr>
 160
 161 <tr><td><a href="xxfi_abort.html">xxfi_abort</a></td><td>message aborted</td></tr>
 162
 163 <tr><td><a href="xxfi_close.html">xxfi_close</a></td><td>connection cleanup</td></tr>
 164
 165 </table>
 166
 167 <p>
 168 The above callbacks should all return one of the following return values,
 169 having the indicated meanings.  Any return other than one of the below
 170 values constitutes an error, and will cause sendmail to terminate its
 171 connection to the offending filter.
 172
 173 <p><a name="conn-spec">Milter</a> distinguishes between recipient-,
 174 message-, and connection-oriented routines.  Recipient-oriented
 175 callbacks may affect the processing of a single message recipient;
 176 message-oriented callbacks, a single message; connection-oriented
 177 callbacks, an entire connection (during which multiple messages may be
 178 delivered to multiple sets of recipients).
 179 <a href="xxfi_envrcpt.html">xxfi_envrcpt</a> is recipient-oriented.
 180 <a href="xxfi_connect.html">xxfi_connect</a>,
 181 <a href="xxfi_helo.html">xxfi_helo</a> and
 182 <a href="xxfi_close.html">xxfi_close</a> are connection-oriented.  All
 183 other callbacks are message-oriented.
 184
 185 <p>
 186 <table border="1" cellspacing=0 cellpadding=2>
 187   <tr bgcolor="#dddddd"><th>Return value</th><th>Description</th></tr>
 188   <tr valign="top">
 189      <td>SMFIS_CONTINUE</td>
 190      <td>Continue processing the current connection, message, or recipient.
 191      </td>
 192   </tr>
 193   <tr valign="top">
 194      <td>SMFIS_REJECT</td>
 195      <td>For a connection-oriented routine, reject this connection; call <a href="xxfi_close.html">xxfi_close</a>.<br>
 196         For a message-oriented routine (except
 197         <a href="xxfi_eom.html">xxfi_eom</a> or
 198         <a href="xxfi_abort.html">xxfi_abort</a>), reject this message.<br>
 199         For a recipient-oriented routine, reject the current recipient (but continue processing the current message).
 200      </td>
 201   </tr>
 202   <tr valign="top">
 203      <td>SMFIS_DISCARD</td>
 204      <td>For a message- or recipient-oriented routine, accept this message, but silently discard it.<br>
 205      SMFIS_DISCARD should not be returned by a connection-oriented routine.
 206      </td>
 207   </tr>
 208   <tr valign="top">
 209      <td>SMFIS_ACCEPT</td>
 210      <td>For a connection-oriented routine, accept this connection without further filter processing; call <a href="xxfi_close.html">xxfi_close</a>.<br>
 211          For a message- or recipient-oriented routine, accept this message without further filtering.<br>
 212      </td>
 213   </tr>
 214   <tr valign="top">
 215      <td>SMFIS_TEMPFAIL</td>
 216      <td>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code.
 217          For a message-oriented routine (except <a href="xxfi_envfrom.html">xxfi_envfrom</a>), fail for this message. <br>
 218          For a connection-oriented routine, fail for this connection; call <a href="xxfi_close.html">xxfi_close</a>. <br>
 219          For a recipient-oriented routine, only fail for the current recipient; continue message processing.
 220      </td>
 221   </tr>
 222 </table>
 223
 224 <hr size="1">
 225 <font size="-1">
 226 Copyright (c) 2000, 2003 Sendmail, Inc. and its suppliers.
 227 All rights reserved.
 228 <br>
 229 By using this file, you agree to the terms and conditions set
 230 forth in the LICENSE.
 231 </font>
 232 </body>
 233 </html>