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

   1 <HTML>
   2 <HEAD><TITLE>Milter API</TITLE></HEAD>
   3 <BODY>
   4 <!--
   5 $Id: api.html,v 1.37 2009/05/19 00:40:52 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.  Message data (senders, recipients, headers, body chunks)
  84 passed to these functions via parameters is copied and does not need to be
  85 preserved (i.e., allocated memory can be freed).
  86
  87 <P>
  88 A filter must have set the appropriate flag (listed below) in the
  89 description passed to <A HREF="smfi_register.html">smfi_register</A>
  90 to call any message modification function.  Failure to do so will
  91 cause the MTA to treat a call to the function as a failure of the
  92 filter, terminating its connection.
  93
  94 <P>
  95 Note that the status returned indicates only whether or not the
  96 filter's message was successfully sent to the MTA, not whether or not
  97 the MTA performed the requested operation.  For example,
  98 <A HREF="smfi_addheader.html">smfi_addheader</A>, when called with an
  99 illegal header name, will return MI_SUCCESS even though the MTA may
 100 later refuse to add the illegal header.
 101 <P>
 102 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH><TH>SMFIF_* flag</TR>
 103 <TR><TD><A HREF="smfi_addheader.html">smfi_addheader</A></TD><TD>Add a header to
 104 the message.</TD><TD>SMFIF_ADDHDRS</TD></TR>
 105
 106 <TR><TD><A HREF="smfi_chgheader.html">smfi_chgheader</A></TD><TD>Change or delete a header.</TD><TD>SMFIF_CHGHDRS</TD></TR>
 107
 108 <TR><TD><A HREF="smfi_insheader.html">smfi_insheader</A></TD><TD>Insert a
 109 header into the message.</TD><TD>SMFIF_ADDHDRS</TD></TR>
 110
 111 <TR><TD><A HREF="smfi_chgfrom.html">smfi_chgfrom</A></TD><TD>Change the
 112 envelope sender address.</TD><TD>SMFIF_CHGFROM</TD></TR>
 113
 114 <TR><TD><A HREF="smfi_addrcpt.html">smfi_addrcpt</A></TD><TD>Add a recipient to
 115 the envelope.</TD><TD>SMFIF_ADDRCPT</TD></TR>
 116
 117 <TR><TD><A HREF="smfi_addrcpt_par.html">smfi_addrcpt_par</A></TD><TD>Add
 118 a recipient including ESMTP parameter to the envelope.
 119 </TD><TD>SMFIF_ADDRCPT_PAR</TD></TR>
 120
 121 <TR><TD><A HREF="smfi_delrcpt.html">smfi_delrcpt</A></TD><TD>Delete a recipient
 122 from the envelope.</TD><TD>SMFIF_DELRCPT</TD></TR>
 123
 124 <TR><TD><A HREF="smfi_replacebody.html">smfi_replacebody</A></TD><TD>Replace the
 125 body of the message.</TD><TD>SMFIF_CHGBODY</TD></TR>
 126
 127 </TABLE>
 128
 129 <H2>Other Message Handling Functions</H2>
 130
 131 The following functions provide special case handling instructions for
 132 milter or the MTA, without altering the content or status of the message.
 133 <EM>They too may only be called in <A HREF="xxfi_eom.html">xxfi_eom</A></EM>.
 134 All of these functions may invoke additional communication with the MTA.
 135 They will return either MI_SUCCESS or MI_FAILURE to indicate the status of
 136 the operation.
 137
 138 <P>
 139 Note that the status returned indicates only whether or not the
 140 filter's message was successfully sent to the MTA, not whether or not
 141 the MTA performed the requested operation.
 142
 143 <P>
 144 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
 145 <TR><TD><A HREF="smfi_progress.html">smfi_progress</A></TD><TD>Report operation in progress.</TD></TR>
 146
 147 <TR><TD><A HREF="smfi_quarantine.html">smfi_quarantine</A></TD><TD>Quarantine a message.</TD></TR>
 148
 149 </TABLE>
 150
 151 <H2><A NAME="Callbacks">Callbacks</A></H2>
 152
 153 The filter should implement one or more of the following callbacks,
 154 which are registered via <A HREF="smfi_register.html">smfi_register</A>:
 155
 156 <P>
 157 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
 158
 159 <TR><TD><A HREF="xxfi_connect.html">xxfi_connect</A></TD><TD>connection info</TD></TR>
 160
 161 <TR><TD><A HREF="xxfi_helo.html">xxfi_helo</A></TD><TD>SMTP HELO/EHLO command</TD></TR>
 162
 163 <TR><TD><A HREF="xxfi_envfrom.html">xxfi_envfrom</A></TD><TD>envelope sender</TD></TR>
 164
 165 <TR><TD><A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A></TD><TD>envelope recipient</TD></TR>
 166
 167 <TR><TD><A HREF="xxfi_data.html">xxfi_data</A></TD><TD>DATA command</TD></TR>
 168
 169 <TR><TD><A HREF="xxfi_unknown.html">xxfi_unknown</A></TD><TD>Unknown SMTP command</TD></TR>
 170
 171 <TR><TD><A HREF="xxfi_header.html">xxfi_header</A></TD><TD>header</TD></TR>
 172
 173 <TR><TD><A HREF="xxfi_eoh.html">xxfi_eoh</A></TD><TD>end of header</TD></TR>
 174
 175 <TR><TD><A HREF="xxfi_body.html">xxfi_body</A></TD><TD>body block</TD></TR>
 176
 177 <TR><TD><A HREF="xxfi_eom.html">xxfi_eom</A></TD><TD>end of message</TD></TR>
 178
 179 <TR><TD><A HREF="xxfi_abort.html">xxfi_abort</A></TD><TD>message aborted</TD></TR>
 180
 181 <TR><TD><A HREF="xxfi_close.html">xxfi_close</A></TD><TD>connection cleanup</TD></TR>
 182
 183 <TR><TD><A HREF="xxfi_negotiate.html">xxfi_negotiate</A></TD><TD>option negotiattion</TD></TR>
 184
 185 </TABLE>
 186
 187 <P>
 188 The above callbacks should all return one of the following return values,
 189 having the indicated meanings.  Any return other than one of the below
 190 values constitutes an error, and will cause sendmail to terminate its
 191 connection to the offending filter.
 192
 193 <P><A NAME="conn-spec">Milter</A> distinguishes between recipient-,
 194 message-, and connection-oriented routines.  Recipient-oriented
 195 callbacks may affect the processing of a single message recipient;
 196 message-oriented callbacks, a single message; connection-oriented
 197 callbacks, an entire connection (during which multiple messages may be
 198 delivered to multiple sets of recipients).
 199 <A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A> is recipient-oriented.
 200 <A HREF="xxfi_connect.html">xxfi_connect</A>,
 201 <A HREF="xxfi_helo.html">xxfi_helo</A> and
 202 <A HREF="xxfi_close.html">xxfi_close</A> are connection-oriented.  All
 203 other callbacks are message-oriented.
 204
 205 <P>
 206 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2>
 207   <TR BGCOLOR="#dddddd"><TH>Return value</TH><TH>Description</TH></TR>
 208   <TR VALIGN="TOP">
 209      <TD>SMFIS_CONTINUE</TD>
 210      <TD>Continue processing the current connection, message, or recipient.
 211      </TD>
 212   </TR>
 213   <TR VALIGN="TOP">
 214      <TD>SMFIS_REJECT</TD>
 215      <TD>For a connection-oriented routine, reject this connection; call <A HREF="xxfi_close.html">xxfi_close</A>.<BR>
 216         For a message-oriented routine (except
 217         <A HREF="xxfi_eom.html">xxfi_eom</A> or
 218         <A HREF="xxfi_abort.html">xxfi_abort</A>), reject this message.<BR>
 219         For a recipient-oriented routine, reject the current recipient (but continue processing the current message).
 220      </TD>
 221   </TR>
 222   <TR valign="top">
 223      <TD>SMFIS_DISCARD</TD>
 224      <TD>For a message- or recipient-oriented routine, accept this message, but silently discard it.<BR>
 225      SMFIS_DISCARD should not be returned by a connection-oriented routine.
 226      </TD>
 227   </TR>
 228   <TR valign="top">
 229      <TD>SMFIS_ACCEPT</TD>
 230      <TD>For a connection-oriented routine, accept this connection without further filter processing; call <A HREF="xxfi_close.html">xxfi_close</A>.<BR>
 231          For a message- or recipient-oriented routine, accept this message without further filtering.<BR>
 232      </TD>
 233   </TR>
 234   <TR valign="top">
 235      <TD>SMFIS_TEMPFAIL</TD>
 236      <TD>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code.
 237          For a message-oriented routine (except <A HREF="xxfi_envfrom.html">xxfi_envfrom</A>), fail for this message. <BR>
 238          For a connection-oriented routine, fail for this connection; call <A HREF="xxfi_close.html">xxfi_close</A>. <BR>
 239          For a recipient-oriented routine, only fail for the current recipient; continue message processing.
 240      </TD>
 241   </TR>
 242
 243   <TR valign="top">
 244      <TD><A NAME="SMFIS_SKIP">SMFIS_SKIP</A></TD>
 245      <TD>Skip further callbacks of the same type in this transaction.
 246         Currently this return value is only allowed in
 247         <A HREF="xxfi_body.html">xxfi_body()</A>.
 248         It can be used if a milter has received sufficiently many
 249         body chunks to make a decision, but still wants to invoke
 250         message modification functions that are only allowed to be called from
 251         <A HREF="xxfi_eom.html">xxfi_eom()</A>.
 252         Note: the milter <EM>must</EM>
 253         <A HREF="xxfi_negotiate.html">negotiate</A>
 254         this behavior with the MTA, i.e., it must check whether
 255         the protocol action
 256         <A HREF="xxfi_negotiate.html#SMFIP_SKIP"><CODE>SMFIP_SKIP</CODE></A>
 257         is available and if so, the milter must request it.
 258      </TD>
 259   </TR>
 260
 261   <TR valign="top">
 262      <TD><A NAME="SMFIS_NOREPLY">SMFIS_NOREPLY</A></TD>
 263      <TD>Do not send a reply back to the MTA.
 264         The milter <EM>must</EM>
 265         <A HREF="xxfi_negotiate.html">negotiate</A>
 266         this behavior with the MTA, i.e., it must check whether
 267         the appropriate protocol action
 268         <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
 269         is available and if so, the milter must request it.
 270         If you set the
 271         <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
 272         protocol action for a callback, that callback <EM>must</EM>
 273         always reply with
 274         SMFIS_NOREPLY.
 275         Using any other reply code is a violation of the API.
 276         If in some cases your callback may return another value
 277         (e.g., due to some resource shortages), then you
 278         <EM>must not</EM> set
 279         <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
 280         and you must use
 281         SMFIS_CONTINUE as the default return code.
 282         (Alternatively you can try to delay reporting the problem to
 283         a later callback for which
 284         <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
 285         is not set.)
 286      </TD>
 287   </TR>
 288
 289 </TABLE>
 290
 291 <H2><A NAME="Miscellaneous">Miscellaneous</A></H2>
 292
 293 <P>
 294 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
 295
 296 <TR><TD><A HREF="smfi_version.html">smfi_version</A></TD><TD>libmilter (runtime) version info</TD></TR>
 297
 298 <TR><TD><A HREF="smfi_setsymlist.html">smfi_setsymlist</A></TD><TD>
 299 Set the list of macros that the milter wants to receive from the MTA
 300 for a protocol stage.
 301 </TD></TR>
 302
 303 </TABLE>
 304
 305 <P>
 306 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Constant</TH><TH>Description</TH></TR>
 307
 308 <TR><TD><A HREF="smfi_version.html">SMFI_VERSION</A></TD><TD>libmilter (compile time) version info</TD></TR>
 309
 310 </TABLE>
 311
 312
 313 <HR SIZE="1">
 314 <FONT SIZE="-1">
 315 Copyright (c) 2000, 2003, 2006, 2009 Sendmail, Inc. and its suppliers.
 316 All rights reserved.
 317 <BR>
 318 By using this file, you agree to the terms and conditions set
 319 forth in the LICENSE.
 320 </FONT>
 321 </BODY>
 322 </HTML>