contrib/sendmail/libmilter/docs/api.html

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