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