contrib/sendmail/libmilter/docs/api.html

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