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 <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</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> 83If a milter just wants to inspect the available protocol steps 84and actions, then it can return 85SMFIS_ALL_OPTS 86and the MTA will make all protocol steps and actions available 87to the milter. 88In this case, no values should be assigned to the output parameters 89<CODE>pf0</CODE> - <CODE>pf3</CODE> 90as 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 114request operations and actions during startup. 115In 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> 118structure 119and the protocol steps (f1) were implicitly derived by checking whether 120a callback was defined. 121Due to the extensions in the new milter version, 122such a static selection will not work if a milter requires 123new actions that are not available when talking to an older MTA. 124Hence in the negotiation callback a milter can determine 125which operations are available and dynamically select 126those which it needs and which are offered. 127If some operations are not available, the milter may either fall back 128to an older mode or abort the session and ask the user to upgrade. 129 130<!-- 131<P> 132The protocol steps are defined in 133<CODE>include/libmilter/mfdef.h</CODE>: 134the macros start with 135<CODE>SMFIP_</CODE>. 136--> 137 138<P> 139Protocol steps 140(<CODE>f1</CODE>, <CODE>*pf1</CODE>): 141<UL> 142<LI><A NAME="SMFIP_RCPT_REJ"><CODE>SMFIP_RCPT_REJ</CODE></A>: 143By setting this bit, a milter can request that the 144MTA should also send <CODE>RCPT</CODE> commands that have been rejected 145because the user is unknown (or similar reasons), but not those 146which have been rejected because of syntax errors etc. 147<!-- 148In order for this request to have effect, 149sendmail must have been built with the compile time option 150<TT>_FFR_MILTER_CHECK_REJECTIONS_TOO</TT>. 151--> 152If a milter requests this protocol step, 153then it should check the macro 154<CODE>{rcpt_mailer}</CODE>: 155if that is set to 156<CODE>error</CODE>, 157then the recipient will be rejected by the MTA. 158Usually the macros 159<CODE>{rcpt_host}</CODE> and <CODE>{rcpt_addr}</CODE> 160will contain an enhanced status code and an error text 161in that case, respectively. 162 163<LI><A NAME="SMFIP_SKIP"><CODE>SMFIP_SKIP</CODE></A> 164indicates that the MTA understand the 165<A HREF="api.html#SMFIS_SKIP">SMFIS_SKIP</A> 166return code. 167 168<LI><A NAME="SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 169indicates that the MTA understand the 170<A HREF="api.html#SMFIS_NOREPLY">SMFIS_NOREPLY</A> 171return code. 172There 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> 206indicates that the MTA can send header values with leading space intact. 207If this protocol step is requested, then the MTA will also not add a leading 208space 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 214various SMTP stages, these flags start with: 215<A NAME="SMFIP_NO"><CODE>SMFIP_NO*</CODE></A>. 216Setting 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 238For each of these xxfi_* callbacks that a milter does not use 239the corresponding flag <EM>should</EM> be set in 240<CODE>*pf1</CODE>. 241 242</UL> 243 244<P> 245The available actions 246(<CODE>f0</CODE>, <CODE>*pf0</CODE>) 247are 248<!-- 249defined in 250<CODE>include/libmilter/mfapi.h</CODE>: 251the macros start with 252<CODE>SMFIF_</CODE>; 253these are 254--> 255described 256<A HREF="smfi_register.html#flags">elsewhere (xxfi_flags)</A>. 257 258<P> 259If a milter returns SMFIS_CONTINUE, then it <EM>must</EM> 260set the desired actions and protocol steps 261via the (output) parameters 262<CODE>pf0</CODE> 263and 264<CODE>pf1</CODE> 265(which correspond to 266<CODE>f0</CODE> 267and 268<CODE>f1</CODE>, respectively). 269The (output) parameters 270<CODE>pf2</CODE> and 271<CODE>pf3</CODE> 272should 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"> 280Copyright (c) 2006 Proofpoint, Inc. and its suppliers. 281All rights reserved. 282<BR> 283By using this file, you agree to the terms and conditions set 284forth in the LICENSE. 285</FONT> 286</BODY> 287</HTML> 288