contrib/sendmail/libmilter/docs/api.html

   1 <HTML>
   2 <HEAD><TITLE>Milter API</TITLE></HEAD>
   3 <BODY>
   4 <!--
   5 $Id: api.html,v 1.35 2006/11/30 23:09:23 ca Exp $
   6 -->
   7 <H1>Milter API</H1>
   8
   9 <H2>Contents</H2>
  10 <UL>
  11     <LI><A HREF="#LibraryControlFunctions">Library Control Functions</A>
  12     <LI><A HREF="#DataAccessFunctions">Data Access Functions</A>
  13     <LI><A HREF="#MessageModificationFunctions">Message Modification Functions</A>
  14     <LI><A HREF="#Callbacks">Callbacks</A>
  15     <LI><A HREF="#Miscellaneous">Miscellaneous</A>
  16 </UL>
  17
  18 <H2><A NAME="LibraryControlFunctions">Library Control Functions</A></H2>
  19
  20 Before handing control to libmilter (by calling
  21 <A HREF="smfi_main.html">smfi_main</A>), a filter may call the following
  22 functions to set libmilter parameters.
  23 In particular, the filter must call
  24 <A HREF="smfi_register.html">smfi_register</A> to register its callbacks.
  25 Each function will return either MI_SUCCESS or MI_FAILURE to
  26 indicate the status of the operation.
  27
  28 <P>
  29 None of these functions communicate with the MTA.  All alter the
  30 library's state, some of which is communicated to the MTA inside
  31 <A HREF="smfi_main.html">smfi_main</A>.
  32
  33 <P>
  34 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
  35
  36 <TR><TD><A HREF="smfi_opensocket.html">smfi_opensocket</A></TD><TD>Try to create the interface socket.</TD></TR>
  37
  38 <TR><TD><A HREF="smfi_register.html">smfi_register</A></TD><TD>Register a filter.</TD></TR>
  39
  40 <TR><TD><A HREF="smfi_setconn.html">smfi_setconn</A></TD><TD>Specify socket to use.</TD></TR>
  41
  42 <TR><TD><A HREF="smfi_settimeout.html">smfi_settimeout</A></TD><TD>Set timeout.</TD></TR>
  43
  44 <TR><TD><A HREF="smfi_setbacklog.html">smfi_setbacklog</A></TD><TD>Define the incoming <CODE>listen(2)</CODE> queue size.</TD></TR>
  45
  46 <TR><TD><A HREF="smfi_setdbg.html">smfi_setdbg</A></TD><TD>Set the milter library debugging (tracing) level.</TD></TR>
  47
  48 <TR><TD><A HREF="smfi_stop.html">smfi_stop</A></TD><TD>Cause an orderly shutdown.</TD></TR>
  49
  50 <TR><TD><A HREF="smfi_main.html">smfi_main</A></TD><TD>Hand control to libmilter.</TD></TR>
  51
  52 </TABLE>
  53
  54 <H2><A NAME="DataAccessFunctions">Data Access Functions</A></H2>
  55
  56 The following functions may be called from within the filter-defined callbacks
  57 to access information about the current connection or message.
  58 <P>
  59 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR bgcolor="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
  60 <TR><TD><A HREF="smfi_getsymval.html">smfi_getsymval</A></TD><TD>Return the value
  61 of a symbol.</TD></TR>
  62
  63 <TR><TD><A HREF="smfi_getpriv.html">smfi_getpriv</A></TD><TD>Get the private data
  64 pointer.</TD></TR>
  65
  66 <TR><TD><A HREF="smfi_setpriv.html">smfi_setpriv</A></TD><TD>Set the private data
  67 pointer.</TD></TR>
  68
  69 <TR><TD><A HREF="smfi_setreply.html">smfi_setreply</A></TD><TD>Set the specific
  70 reply code to be used.</TD></TR>
  71
  72 <TR><TD><A HREF="smfi_setmlreply.html">smfi_setmlreply</A></TD><TD>Set the
  73 specific multi-line reply to be used.</TD></TR>
  74
  75 </TABLE>
  76
  77 <H2><A NAME="MessageModificationFunctions">Message Modification Functions</A></H2>
  78
  79 The following functions change a message's contents and attributes.
  80 <EM>They may only be called in <A HREF="xxfi_eom.html">xxfi_eom</A></EM>.
  81 All of these functions may invoke additional communication with the MTA.
  82 They will return either MI_SUCCESS or MI_FAILURE to indicate the status of
  83 the operation.
  84
  85 <P>
  86 A filter must have set the appropriate flag (listed below) in the
  87 description passed to <A HREF="smfi_register.html">smfi_register</A>
  88 to call any message modification function.  Failure to do so will
  89 cause the MTA to treat a call to the function as a failure of the
  90 filter, terminating its connection.
  91
  92 <P>
  93 Note that the status returned indicates only whether or not the
  94 filter's message was successfully sent to the MTA, not whether or not
  95 the MTA performed the requested operation.  For example,
  96 <A HREF="smfi_addheader.html">smfi_addheader</A>, when called with an
  97 illegal header name, will return MI_SUCCESS even though the MTA may
  98 later refuse to add the illegal header.
  99 <P>
 100 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH><TH>SMFIF_* flag</TR>
 101 <TR><TD><A HREF="smfi_addheader.html">smfi_addheader</A></TD><TD>Add a header to
 102 the message.</TD><TD>SMFIF_ADDHDRS</TD></TR>
 103
 104 <TR><TD><A HREF="smfi_chgheader.html">smfi_chgheader</A></TD><TD>Change or delete a header.</TD><TD>SMFIF_CHGHDRS</TD></TR>
 105
 106 <TR><TD><A HREF="smfi_insheader.html">smfi_insheader</A></TD><TD>Insert a
 107 header into the message.</TD><TD>SMFIF_ADDHDRS</TD></TR>
 108
 109 <TR><TD><A HREF="smfi_chgfrom.html">smfi_chgfrom</A></TD><TD>Change the
 110 envelope sender address.</TD><TD>SMFIF_CHGFROM</TD></TR>
 111
 112 <TR><TD><A HREF="smfi_addrcpt.html">smfi_addrcpt</A></TD><TD>Add a recipient to
 113 the envelope.</TD><TD>SMFIF_ADDRCPT</TD></TR>
 114
 115 <TR><TD><A HREF="smfi_addrcpt_par.html">smfi_addrcpt_par</A></TD><TD>Add
 116 a recipient including ESMTP parameter to the envelope.
 117 </TD><TD>SMFIF_ADDRCPT_PAR</TD></TR>
 118
 119 <TR><TD><A HREF="smfi_delrcpt.html">smfi_delrcpt</A></TD><TD>Delete a recipient
 120 from the envelope.</TD><TD>SMFIF_DELRCPT</TD></TR>
 121
 122 <TR><TD><A HREF="smfi_replacebody.html">smfi_replacebody</A></TD><TD>Replace the
 123 body of the message.</TD><TD>SMFIF_CHGBODY</TD></TR>
 124
 125 </TABLE>
 126
 127 <H2>Other Message Handling Functions</H2>
 128
 129 The following functions provide special case handling instructions for
 130 milter or the MTA, without altering the content or status of the message.
 131 <EM>They too may only be called in <A HREF="xxfi_eom.html">xxfi_eom</A></EM>.
 132 All of these functions may invoke additional communication with the MTA.
 133 They will return either MI_SUCCESS or MI_FAILURE to indicate the status of
 134 the operation.
 135
 136 <P>
 137 Note that the status returned indicates only whether or not the
 138 filter's message was successfully sent to the MTA, not whether or not
 139 the MTA performed the requested operation.
 140
 141 <P>
 142 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
 143 <TR><TD><A HREF="smfi_progress.html">smfi_progress</A></TD><TD>Report operation in progress.</TD></TR>
 144
 145 <TR><TD><A HREF="smfi_quarantine.html">smfi_quarantine</A></TD><TD>Quarantine a message.</TD></TR>
 146
 147 </TABLE>
 148
 149 <H2><A NAME="Callbacks">Callbacks</A></H2>
 150
 151 The filter should implement one or more of the following callbacks,
 152 which are registered via <A HREF="smfi_register.html">smfi_register</A>:
 153
 154 <P>
 155 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
 156
 157 <TR><TD><A HREF="xxfi_connect.html">xxfi_connect</A></TD><TD>connection info</TD></TR>
 158
 159 <TR><TD><A HREF="xxfi_helo.html">xxfi_helo</A></TD><TD>SMTP HELO/EHLO command</TD></TR>
 160
 161 <TR><TD><A HREF="xxfi_envfrom.html">xxfi_envfrom</A></TD><TD>envelope sender</TD></TR>
 162
 163 <TR><TD><A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A></TD><TD>envelope recipient</TD></TR>
 164
 165 <TR><TD><A HREF="xxfi_data.html">xxfi_data</A></TD><TD>DATA command</TD></TR>
 166
 167 <TR><TD><A HREF="xxfi_unknown.html">xxfi_unknown</A></TD><TD>Unknown SMTP command</TD></TR>
 168
 169 <TR><TD><A HREF="xxfi_header.html">xxfi_header</A></TD><TD>header</TD></TR>
 170
 171 <TR><TD><A HREF="xxfi_eoh.html">xxfi_eoh</A></TD><TD>end of header</TD></TR>
 172
 173 <TR><TD><A HREF="xxfi_body.html">xxfi_body</A></TD><TD>body block</TD></TR>
 174
 175 <TR><TD><A HREF="xxfi_eom.html">xxfi_eom</A></TD><TD>end of message</TD></TR>
 176
 177 <TR><TD><A HREF="xxfi_abort.html">xxfi_abort</A></TD><TD>message aborted</TD></TR>
 178
 179 <TR><TD><A HREF="xxfi_close.html">xxfi_close</A></TD><TD>connection cleanup</TD></TR>
 180
 181 <TR><TD><A HREF="xxfi_negotiate.html">xxfi_negotiate</A></TD><TD>option negotiattion</TD></TR>
 182
 183 </TABLE>
 184
 185 <P>
 186 The above callbacks should all return one of the following return values,
 187 having the indicated meanings.  Any return other than one of the below
 188 values constitutes an error, and will cause sendmail to terminate its
 189 connection to the offending filter.
 190
 191 <P><A NAME="conn-spec">Milter</A> distinguishes between recipient-,
 192 message-, and connection-oriented routines.  Recipient-oriented
 193 callbacks may affect the processing of a single message recipient;
 194 message-oriented callbacks, a single message; connection-oriented
 195 callbacks, an entire connection (during which multiple messages may be
 196 delivered to multiple sets of recipients).
 197 <A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A> is recipient-oriented.
 198 <A HREF="xxfi_connect.html">xxfi_connect</A>,
 199 <A HREF="xxfi_helo.html">xxfi_helo</A> and
 200 <A HREF="xxfi_close.html">xxfi_close</A> are connection-oriented.  All
 201 other callbacks are message-oriented.
 202
 203 <P>
 204 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2>
 205   <TR BGCOLOR="#dddddd"><TH>Return value</TH><TH>Description</TH></TR>
 206   <TR VALIGN="TOP">
 207      <TD>SMFIS_CONTINUE</TD>
 208      <TD>Continue processing the current connection, message, or recipient.
 209      </TD>
 210   </TR>
 211   <TR VALIGN="TOP">
 212      <TD>SMFIS_REJECT</TD>
 213      <TD>For a connection-oriented routine, reject this connection; call <A HREF="xxfi_close.html">xxfi_close</A>.<BR>
 214         For a message-oriented routine (except
 215         <A HREF="xxfi_eom.html">xxfi_eom</A> or
 216         <A HREF="xxfi_abort.html">xxfi_abort</A>), reject this message.<BR>
 217         For a recipient-oriented routine, reject the current recipient (but continue processing the current message).
 218      </TD>
 219   </TR>
 220   <TR valign="top">
 221      <TD>SMFIS_DISCARD</TD>
 222      <TD>For a message- or recipient-oriented routine, accept this message, but silently discard it.<BR>
 223      SMFIS_DISCARD should not be returned by a connection-oriented routine.
 224      </TD>
 225   </TR>
 226   <TR valign="top">
 227      <TD>SMFIS_ACCEPT</TD>
 228      <TD>For a connection-oriented routine, accept this connection without further filter processing; call <A HREF="xxfi_close.html">xxfi_close</A>.<BR>
 229          For a message- or recipient-oriented routine, accept this message without further filtering.<BR>
 230      </TD>
 231   </TR>
 232   <TR valign="top">
 233      <TD>SMFIS_TEMPFAIL</TD>
 234      <TD>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code.
 235          For a message-oriented routine (except <A HREF="xxfi_envfrom.html">xxfi_envfrom</A>), fail for this message. <BR>
 236          For a connection-oriented routine, fail for this connection; call <A HREF="xxfi_close.html">xxfi_close</A>. <BR>
 237          For a recipient-oriented routine, only fail for the current recipient; continue message processing.
 238      </TD>
 239   </TR>
 240
 241   <TR valign="top">
 242      <TD><A NAME="SMFIS_SKIP">SMFIS_SKIP</A></TD>
 243      <TD>Skip further callbacks of the same type in this transaction.
 244         Currently this return value is only allowed in
 245         <A HREF="xxfi_body.html">xxfi_body()</A>.
 246         It can be used if a milter has received sufficiently many
 247         body chunks to make a decision, but still wants to invoke
 248         message modification functions that are only allowed to be called from
 249         <A HREF="xxfi_eom.html">xxfi_eom()</A>.
 250         Note: the milter <EM>must</EM>
 251         <A HREF="xxfi_negotiate.html">negotiate</A>
 252         this behavior with the MTA, i.e., it must check whether
 253         the protocol action
 254         <A HREF="xxfi_negotiate.html#SMFIP_SKIP"><CODE>SMFIP_SKIP</CODE></A>
 255         is available and if so, the milter must request it.
 256      </TD>
 257   </TR>
 258
 259   <TR valign="top">
 260      <TD><A NAME="SMFIS_NOREPLY">SMFIS_NOREPLY</A></TD>
 261      <TD>Do not send a reply back to the MTA.
 262         The milter <EM>must</EM>
 263         <A HREF="xxfi_negotiate.html">negotiate</A>
 264         this behavior with the MTA, i.e., it must check whether
 265         the appropriate protocol action
 266         <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
 267         is available and if so, the milter must request it.
 268         If you set the
 269         <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
 270         protocol action for a callback, that callback <EM>must</EM>
 271         always reply with
 272         SMFIS_NOREPLY.
 273         Using any other reply code is a violation of the API.
 274         If in some cases your callback may return another value
 275         (e.g., due to some resource shortages), then you
 276         <EM>must not</EM> set
 277         <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
 278         and you must use
 279         SMFIS_CONTINUE as the default return code.
 280         (Alternatively you can try to delay reporting the problem to
 281         a later callback for which
 282         <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
 283         is not set.)
 284      </TD>
 285   </TR>
 286
 287 </TABLE>
 288
 289 <H2><A NAME="Miscellaneous">Miscellaneous</A></H2>
 290
 291 <P>
 292 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
 293
 294 <TR><TD><A HREF="smfi_version.html">smfi_version</A></TD><TD>libmilter (runtime) version info</TD></TR>
 295
 296 <TR><TD><A HREF="smfi_setsymlist.html">smfi_setsymlist</A></TD><TD>
 297 Set the list of macros that the milter wants to receive from the MTA
 298 for a protocol stage.
 299 </TD></TR>
 300
 301 </TABLE>
 302
 303 <P>
 304 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Constant</TH><TH>Description</TH></TR>
 305
 306 <TR><TD><A HREF="smfi_version.html">SMFI_VERSION</A></TD><TD>libmilter (compile time) version info</TD></TR>
 307
 308 </TABLE>
 309
 310
 311 <HR SIZE="1">
 312 <FONT SIZE="-1">
 313 Copyright (c) 2000, 2003, 2006 Sendmail, Inc. and its suppliers.
 314 All rights reserved.
 315 <BR>
 316 By using this file, you agree to the terms and conditions set
 317 forth in the LICENSE.
 318 </FONT>
 319 </BODY>
 320 </HTML>