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