contrib/sendmail/libmilter/docs/xxfi_negotiate.html

   1 <HTML>
   2 <HEAD><TITLE>xxfi_negotiate</TITLE></HEAD>
   3 <BODY>
   4 <!--
   5 $Id: xxfi_negotiate.html,v 1.24 2013-11-22 20:51:39 ca Exp $
   6 -->
   7 <H1>xxfi_negotiate</H1>
   8
   9 <TABLE border="0" cellspacing=4 cellpadding=4>
  10 <!---------- Synopsis ----------->
  11 <TR><TH valign="top" align=left width=100>SYNOPSIS</TH><TD>
  12 <PRE>
  13 #include &lt;libmilter/mfapi.h&gt;
  14 #include &lt;libmilter/mfdef.h&gt;
  15 sfsistat (*xxfi_negotiate)(
  16         SMFICTX    *ctx,
  17         unsigned long f0,
  18         unsigned long f1,
  19         unsigned long f2,
  20         unsigned long f3,
  21         unsigned long *pf0,
  22         unsigned long *pf1,
  23         unsigned long *pf2,
  24         unsigned long *pf3);
  25 </PRE>
  26 </TD></TR>
  27 <!----------- Description ---------->
  28 <TR><TH valign="top" align=left>DESCRIPTION</TH><TD>
  29 <TABLE border="1" cellspacing=1 cellpadding=4>
  30 <TR>
  31 <TH valign="top" align=left width=80>Called When</TH>
  32 <TD>Once, at the start of each SMTP connection.</TD>
  33 </TR>
  34 <TR>
  35 <TH valign="top" align=left width=80>Default Behavior</TH>
  36 <TD>Return SMFIS_ALL_OPTS to change nothing.</TD>
  37 </TR>
  38 </TABLE>
  39 </TD></TR>
  40
  41 <!----------- Arguments ---------->
  42 <TR><TH valign="top" align=left>ARGUMENTS</TH><TD>
  43     <TABLE border="1" cellspacing=0>
  44     <TR bgcolor="#dddddd"><TH>Argument</TH><TH>Description</TH></TR>
  45     <TR><TD>ctx</TD>
  46         <TD>the opaque context structure.
  47         </TD></TR>
  48     <TR><TD>f0</TD>
  49         <TD>the actions offered by the MTA.
  50         </TD></TR>
  51     <TR><TD>f1</TD>
  52         <TD>the protocol steps offered by the MTA.
  53         </TD></TR>
  54     <TR><TD>f2</TD>
  55         <TD>for future extensions.
  56         </TD></TR>
  57     <TR><TD>f3</TD>
  58         <TD>for future extensions.
  59         </TD></TR>
  60     <TR><TD>pf0</TD>
  61         <TD>the actions requested by the milter.
  62         </TD></TR>
  63     <TR><TD>pf1</TD>
  64         <TD>the protocol steps requested by the milter.
  65         </TD></TR>
  66     <TR><TD>pf2</TD>
  67         <TD>for future extensions.
  68         </TD></TR>
  69     <TR><TD>pf3</TD>
  70         <TD>for future extensions.
  71         </TD></TR>
  72     </TABLE>
  73 </TD></TR>
  74
  75 <!----------- Return values ---------->
  76 <TR>
  77 <TH valign="top" align=left>SPECIAL RETURN VALUES</TH>
  78 <TD><TABLE border="1" cellspacing=0>
  79   <TR bgcolor="#dddddd"><TH>Return value</TH><TH>Description</TH></TR>
  80   <TR valign="top">
  81      <TD>SMFIS_ALL_OPTS</TD>
  82      <TD>
  83 If a milter just wants to inspect the available protocol steps
  84 and actions, then it can return
  85 SMFIS_ALL_OPTS
  86 and the MTA will make all protocol steps and actions available
  87 to the milter.
  88 In this case, no values should be assigned to the output parameters
  89 <CODE>pf0</CODE> - <CODE>pf3</CODE>
  90 as they will be ignored.
  91      </TD>
  92   </TR>
  93   <TR valign="top">
  94      <TD>SMFIS_REJECT</TD>
  95      <TD>Milter startup fails and it will not be contacted again
  96 (for the current connection).
  97      </TD>
  98   </TR>
  99   <TR valign="top">
 100      <TD>SMFIS_CONTINUE</TD>
 101      <TD>Continue processing.
 102         In this case the milter <EM>must</EM> set all output parameters
 103         <CODE>pf0</CODE> - <CODE>pf3</CODE>.
 104         See below for an explanation how to set those output parameters.
 105      </TD>
 106   </TR>
 107 </TABLE>
 108 </TD></TR>
 109
 110 <!----------- Notes ---------->
 111 <TR>
 112 <TH valign="top" align=left>NOTES</TH>
 113 <TD>This function allows a milter to dynamically determine and
 114 request operations and actions during startup.
 115 In previous versions, the actions (f0) were fixed in the
 116 <A HREF="smfi_register.html#flags">flags</A> field of the
 117 <A HREF="smfi_register.html#smfiDesc">smfiDesc</A>
 118 structure
 119 and the protocol steps (f1) were implicitly derived by checking whether
 120 a callback was defined.
 121 Due to the extensions in the new milter version,
 122 such a static selection will not work if a milter requires
 123 new actions that are not available when talking to an older MTA.
 124 Hence in the negotiation callback a milter can determine
 125 which operations are available and dynamically select
 126 those which it needs and which are offered.
 127 If some operations are not available, the milter may either fall back
 128 to an older mode or abort the session and ask the user to upgrade.
 129
 130 <!--
 131 <P>
 132 The protocol steps are defined in
 133 <CODE>include/libmilter/mfdef.h</CODE>:
 134 the macros start with
 135 <CODE>SMFIP_</CODE>.
 136 -->
 137
 138 <P>
 139 Protocol steps
 140 (<CODE>f1</CODE>, <CODE>*pf1</CODE>):
 141 <UL>
 142 <LI><A NAME="SMFIP_RCPT_REJ"><CODE>SMFIP_RCPT_REJ</CODE></A>:
 143 By setting this bit, a milter can request that the
 144 MTA should also send <CODE>RCPT</CODE> commands that have been rejected
 145 because the user is unknown (or similar reasons), but not those
 146 which have been rejected because of syntax errors etc.
 147 <!--
 148 In order for this request to have effect,
 149 sendmail must have been built with the compile time option
 150 <TT>_FFR_MILTER_CHECK_REJECTIONS_TOO</TT>.
 151 -->
 152 If a milter requests this protocol step,
 153 then it should check the macro
 154 <CODE>{rcpt_mailer}</CODE>:
 155 if that is set to
 156 <CODE>error</CODE>,
 157 then the recipient will be rejected by the MTA.
 158 Usually the macros
 159 <CODE>{rcpt_host}</CODE> and <CODE>{rcpt_addr}</CODE>
 160 will contain an enhanced status code and an error text
 161 in that case, respectively.
 162
 163 <LI><A NAME="SMFIP_SKIP"><CODE>SMFIP_SKIP</CODE></A>
 164 indicates that the MTA understand the
 165 <A HREF="api.html#SMFIS_SKIP">SMFIS_SKIP</A>
 166 return code.
 167
 168 <LI><A NAME="SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
 169 indicates that the MTA understand the
 170 <A HREF="api.html#SMFIS_NOREPLY">SMFIS_NOREPLY</A>
 171 return code.
 172 There are flags for various protocol stages:
 173
 174 <UL>
 175
 176 <LI><A NAME="SMFIP_NR_CONN"><CODE>SMFIP_NR_CONN</CODE></A>:
 177 <A HREF="xxfi_connect.html">xxfi_connect()</A>
 178
 179 <LI><A NAME="SMFIP_NR_HELO"><CODE>SMFIP_NR_HELO</CODE></A>:
 180 <A HREF="xxfi_helo.html">xxfi_helo()</A>
 181
 182 <LI><A NAME="SMFIP_NR_MAIL"><CODE>SMFIP_NR_MAIL</CODE></A>:
 183 <A HREF="xxfi_envfrom.html">xxfi_envfrom()</A>
 184
 185 <LI><A NAME="SMFIP_NR_RCPT"><CODE>SMFIP_NR_RCPT</CODE></A>:
 186 <A HREF="xxfi_envrcpt.html">xxfi_envrcpt()</A>
 187
 188 <LI><A NAME="SMFIP_NR_DATA"><CODE>SMFIP_NR_DATA</CODE></A>:
 189 <A HREF="xxfi_data.html">xxfi_data()</A>
 190
 191 <LI><A NAME="SMFIP_NR_UNKN"><CODE>SMFIP_NR_UNKN</CODE></A>:
 192 <A HREF="xxfi_unknown.html">xxfi_unknown()</A>
 193
 194 <LI><A NAME="SMFIP_NR_EOH"><CODE>SMFIP_NR_EOH</CODE></A>:
 195 <A HREF="xxfi_eoh.html">xxfi_eoh()</A>
 196
 197 <LI><A NAME="SMFIP_NR_BODY"><CODE>SMFIP_NR_BODY</CODE></A>:
 198 <A HREF="xxfi_body.html">xxfi_body()</A>
 199
 200 <LI><A NAME="SMFIP_NR_HDR"><CODE>SMFIP_NR_HDR</CODE></A>:
 201 <A HREF="xxfi_header.html">xxfi_header()</A>
 202
 203 </UL>
 204
 205 <LI><A NAME="SMFIP_HDR_LEADSPC"><CODE>SMFIP_HDR_LEADSPC</CODE></A>
 206 indicates that the MTA can send header values with leading space intact.
 207 If this protocol step is requested, then the MTA will also not add a leading
 208 space to headers when they are added, inserted, or changed.
 209
 210 <!--
 211 :'a,.s;^#define \(SMFIP_NO[A-Z]*\)[     ].*;<LI><A NAME="\1"><CODE>\1</CODE></A>:;
 212 -->
 213 <LI>The MTA can be instructed not to send information about
 214 various SMTP stages, these flags start with:
 215 <A NAME="SMFIP_NO"><CODE>SMFIP_NO*</CODE></A>.
 216 Setting any of these flags affects all connections.
 217 <UL>
 218 <LI><A NAME="SMFIP_NOCONNECT"><CODE>SMFIP_NOCONNECT</CODE></A>:
 219 <A HREF="xxfi_connect.html">xxfi_connect()</A>
 220 <LI><A NAME="SMFIP_NOHELO"><CODE>SMFIP_NOHELO</CODE></A>:
 221 <A HREF="xxfi_helo.html">xxfi_helo()</A>
 222 <LI><A NAME="SMFIP_NOMAIL"><CODE>SMFIP_NOMAIL</CODE></A>:
 223 <A HREF="xxfi_envfrom.html">xxfi_envfrom()</A>
 224 <LI><A NAME="SMFIP_NORCPT"><CODE>SMFIP_NORCPT</CODE></A>:
 225 <A HREF="xxfi_envrcpt.html">xxfi_envrcpt()</A>
 226 <LI><A NAME="SMFIP_NOBODY"><CODE>SMFIP_NOBODY</CODE></A>:
 227 <A HREF="xxfi_body.html">xxfi_body()</A>
 228 <LI><A NAME="SMFIP_NOHDRS"><CODE>SMFIP_NOHDRS</CODE></A>:
 229 <A HREF="xxfi_header.html">xxfi_header()</A>
 230 <LI><A NAME="SMFIP_NOEOH"><CODE>SMFIP_NOEOH</CODE></A>:
 231 <A HREF="xxfi_eoh.html">xxfi_eoh()</A>
 232 <LI><A NAME="SMFIP_NOUNKNOWN"><CODE>SMFIP_NOUNKNOWN</CODE></A>:
 233 <A HREF="xxfi_unknown.html">xxfi_unknown()</A>
 234 <LI><A NAME="SMFIP_NODATA"><CODE>SMFIP_NODATA</CODE></A>:
 235 <A HREF="xxfi_data.html">xxfi_data()</A>
 236 </UL>
 237
 238 For each of these xxfi_* callbacks that a milter does not use
 239 the corresponding flag <EM>should</EM> be set in
 240 <CODE>*pf1</CODE>.
 241
 242 </UL>
 243
 244 <P>
 245 The available actions
 246 (<CODE>f0</CODE>, <CODE>*pf0</CODE>)
 247 are
 248 <!--
 249 defined in
 250 <CODE>include/libmilter/mfapi.h</CODE>:
 251 the macros start with
 252 <CODE>SMFIF_</CODE>;
 253 these are
 254 -->
 255 described
 256 <A HREF="smfi_register.html#flags">elsewhere (xxfi_flags)</A>.
 257
 258 <P>
 259 If a milter returns SMFIS_CONTINUE, then it <EM>must</EM>
 260 set the desired actions and protocol steps
 261 via the (output) parameters
 262 <CODE>pf0</CODE>
 263 and
 264 <CODE>pf1</CODE>
 265 (which correspond to
 266 <CODE>f0</CODE>
 267 and
 268 <CODE>f1</CODE>, respectively).
 269 The (output) parameters
 270 <CODE>pf2</CODE> and
 271 <CODE>pf3</CODE>
 272 should be set to 0 for compatibility with future versions.
 273
 274 </TD>
 275 </TR>
 276 </TABLE>
 277
 278 <HR size="1">
 279 <FONT size="-1">
 280 Copyright (c) 2006 Proofpoint, Inc. and its suppliers.
 281 All rights reserved.
 282 <BR>
 283 By using this file, you agree to the terms and conditions set
 284 forth in the LICENSE.
 285 </FONT>
 286 </BODY>
 287 </HTML>