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 <libmilter/mfapi.h> 14#include <libmilter/mfdef.h> 15sfsistat (*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> 79If a milter just wants to inspect the available protocol steps 80and actions, then it can return 81SMFIS_ALL_OPTS 82and the MTA will make all protocol steps and actions available 83to the milter. 84In this case, no values should be assigned to the output parameters 85<CODE>pf0</CODE> - <CODE>pf3</CODE> 86as 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 110request operations and actions during startup. 111In 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> 114structure 115and the protocol steps (f1) were implicitly derived by checking whether 116a callback was defined. 117Due to the extensions in the new milter version, 118such a static selection will not work if a milter requires 119new actions that are not available when talking to an older MTA. 120Hence in the negotiation callback a milter can determine 121which operations are available and dynamically select 122those which it needs and which are offered. 123If some operations are not available, the milter may either fall back 124to an older mode or abort the session and ask the user to upgrade. 125 126<!-- 127<P> 128The protocol steps are defined in 129<CODE>include/libmilter/mfdef.h</CODE>: 130the macros start with 131<CODE>SMFIP_</CODE>. 132--> 133 134<P> 135Protocol steps 136(<CODE>f1</CODE>, <CODE>*pf1</CODE>): 137<UL> 138<LI><A NAME="SMFIP_RCPT_REJ"><CODE>SMFIP_RCPT_REJ</CODE></A>: 139By setting this bit, a milter can request that the 140MTA should also send <CODE>RCPT</CODE> commands that have been rejected 141because the user is unknown (or similar reasons), but not those 142which have been rejected because of syntax errors etc. 143If a milter requests this protocol step, 144then it should check the macro 145<CODE>{rcpt_mailer}</CODE>: 146if that is set to 147<CODE>error</CODE>, 148then the recipient will be rejected by the MTA. 149Usually the macros 150<CODE>{rcpt_host}</CODE> and <CODE>{rcpt_addr}</CODE> 151will contain an enhanced status code and an error text 152in that case, respectively. 153 154<LI><A NAME="SMFIP_SKIP"><CODE>SMFIP_SKIP</CODE></A> 155indicates that the MTA understand the 156<A HREF="api.html#SMFIS_SKIP">SMFIS_SKIP</A> 157return code. 158 159<LI><A NAME="SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 160indicates that the MTA understand the 161<A HREF="api.html#SMFIS_NOREPLY">SMFIS_NOREPLY</A> 162return code. 163There 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> 197indicates that the MTA can send header values with leading space intact. 198If this protocol step is requested, then the MTA will also not add a leading 199space 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 205various 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 228For each of these xxfi_* callbacks that a milter does not use 229the corresponding flag <EM>should</EM> be set in 230<CODE>*pf1</CODE>. 231 232</UL> 233 234<P> 235The available actions 236(<CODE>f0</CODE>, <CODE>*pf0</CODE>) 237are 238<!-- 239defined in 240<CODE>include/libmilter/mfapi.h</CODE>: 241the macros start with 242<CODE>SMFIF_</CODE>; 243these are 244--> 245described 246<A HREF="smfi_register.html#flags">elsewhere (xxfi_flags)</A>. 247 248<P> 249If a milter returns SMFIS_CONTINUE, then it <EM>must</EM> 250set the desired actions and protocol steps 251via the (output) parameters 252<CODE>pf0</CODE> 253and 254<CODE>pf1</CODE> 255(which correspond to 256<CODE>f0</CODE> 257and 258<CODE>f1</CODE>, respectively). 259The (output) parameters 260<CODE>pf2</CODE> and 261<CODE>pf3</CODE> 262should 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"> 270Copyright (c) 2006 Sendmail, Inc. and its suppliers. 271All rights reserved. 272<BR> 273By using this file, you agree to the terms and conditions set 274forth in the LICENSE. 275</FONT> 276</BODY> 277</HTML> 278