1168515Sgshapiro<HTML> 2168515Sgshapiro<HEAD><TITLE>xxfi_negotiate</TITLE></HEAD> 3168515Sgshapiro<BODY> 4168515Sgshapiro<!-- 5266527Sgshapiro$Id: xxfi_negotiate.html,v 1.24 2013-11-22 20:51:39 ca Exp $ 6168515Sgshapiro--> 7168515Sgshapiro<H1>xxfi_negotiate</H1> 8168515Sgshapiro 9168515Sgshapiro<TABLE border="0" cellspacing=4 cellpadding=4> 10168515Sgshapiro<!---------- Synopsis -----------> 11168515Sgshapiro<TR><TH valign="top" align=left width=100>SYNOPSIS</TH><TD> 12168515Sgshapiro<PRE> 13168515Sgshapiro#include <libmilter/mfapi.h> 14168515Sgshapiro#include <libmilter/mfdef.h> 15168515Sgshapirosfsistat (*xxfi_negotiate)( 16363466Sgshapiro SMFICTX *ctx, 17168515Sgshapiro unsigned long f0, 18168515Sgshapiro unsigned long f1, 19168515Sgshapiro unsigned long f2, 20168515Sgshapiro unsigned long f3, 21168515Sgshapiro unsigned long *pf0, 22168515Sgshapiro unsigned long *pf1, 23168515Sgshapiro unsigned long *pf2, 24168515Sgshapiro unsigned long *pf3); 25168515Sgshapiro</PRE> 26168515Sgshapiro</TD></TR> 27168515Sgshapiro<!----------- Description ----------> 28168515Sgshapiro<TR><TH valign="top" align=left>DESCRIPTION</TH><TD> 29168515Sgshapiro<TABLE border="1" cellspacing=1 cellpadding=4> 30168515Sgshapiro<TR> 31168515Sgshapiro<TH valign="top" align=left width=80>Called When</TH> 32168515Sgshapiro<TD>Once, at the start of each SMTP connection.</TD> 33168515Sgshapiro</TR> 34168515Sgshapiro<TR> 35168515Sgshapiro<TH valign="top" align=left width=80>Default Behavior</TH> 36168515Sgshapiro<TD>Return SMFIS_ALL_OPTS to change nothing.</TD> 37168515Sgshapiro</TR> 38168515Sgshapiro</TABLE> 39363466Sgshapiro</TD></TR> 40363466Sgshapiro 41168515Sgshapiro<!----------- Arguments ----------> 42168515Sgshapiro<TR><TH valign="top" align=left>ARGUMENTS</TH><TD> 43168515Sgshapiro <TABLE border="1" cellspacing=0> 44168515Sgshapiro <TR bgcolor="#dddddd"><TH>Argument</TH><TH>Description</TH></TR> 45168515Sgshapiro <TR><TD>ctx</TD> 46168515Sgshapiro <TD>the opaque context structure. 47168515Sgshapiro </TD></TR> 48168515Sgshapiro <TR><TD>f0</TD> 49168515Sgshapiro <TD>the actions offered by the MTA. 50168515Sgshapiro </TD></TR> 51168515Sgshapiro <TR><TD>f1</TD> 52168515Sgshapiro <TD>the protocol steps offered by the MTA. 53363466Sgshapiro </TD></TR> 54168515Sgshapiro <TR><TD>f2</TD> 55168515Sgshapiro <TD>for future extensions. 56168515Sgshapiro </TD></TR> 57168515Sgshapiro <TR><TD>f3</TD> 58168515Sgshapiro <TD>for future extensions. 59168515Sgshapiro </TD></TR> 60168515Sgshapiro <TR><TD>pf0</TD> 61168515Sgshapiro <TD>the actions requested by the milter. 62168515Sgshapiro </TD></TR> 63168515Sgshapiro <TR><TD>pf1</TD> 64168515Sgshapiro <TD>the protocol steps requested by the milter. 65363466Sgshapiro </TD></TR> 66168515Sgshapiro <TR><TD>pf2</TD> 67168515Sgshapiro <TD>for future extensions. 68168515Sgshapiro </TD></TR> 69168515Sgshapiro <TR><TD>pf3</TD> 70168515Sgshapiro <TD>for future extensions. 71168515Sgshapiro </TD></TR> 72168515Sgshapiro </TABLE> 73168515Sgshapiro</TD></TR> 74168515Sgshapiro 75168515Sgshapiro<!----------- Return values ----------> 76168515Sgshapiro<TR> 77168515Sgshapiro<TH valign="top" align=left>SPECIAL RETURN VALUES</TH> 78168515Sgshapiro<TD><TABLE border="1" cellspacing=0> 79168515Sgshapiro <TR bgcolor="#dddddd"><TH>Return value</TH><TH>Description</TH></TR> 80168515Sgshapiro <TR valign="top"> 81168515Sgshapiro <TD>SMFIS_ALL_OPTS</TD> 82168515Sgshapiro <TD> 83168515SgshapiroIf a milter just wants to inspect the available protocol steps 84168515Sgshapiroand actions, then it can return 85168515SgshapiroSMFIS_ALL_OPTS 86168515Sgshapiroand the MTA will make all protocol steps and actions available 87168515Sgshapiroto the milter. 88168515SgshapiroIn this case, no values should be assigned to the output parameters 89168515Sgshapiro<CODE>pf0</CODE> - <CODE>pf3</CODE> 90168515Sgshapiroas they will be ignored. 91168515Sgshapiro </TD> 92168515Sgshapiro </TR> 93168515Sgshapiro <TR valign="top"> 94168515Sgshapiro <TD>SMFIS_REJECT</TD> 95168515Sgshapiro <TD>Milter startup fails and it will not be contacted again 96168515Sgshapiro(for the current connection). 97168515Sgshapiro </TD> 98168515Sgshapiro </TR> 99168515Sgshapiro <TR valign="top"> 100168515Sgshapiro <TD>SMFIS_CONTINUE</TD> 101168515Sgshapiro <TD>Continue processing. 102168515Sgshapiro In this case the milter <EM>must</EM> set all output parameters 103168515Sgshapiro <CODE>pf0</CODE> - <CODE>pf3</CODE>. 104168515Sgshapiro See below for an explanation how to set those output parameters. 105168515Sgshapiro </TD> 106168515Sgshapiro </TR> 107168515Sgshapiro</TABLE> 108363466Sgshapiro</TD></TR> 109168515Sgshapiro 110168515Sgshapiro<!----------- Notes ----------> 111168515Sgshapiro<TR> 112363466Sgshapiro<TH valign="top" align=left>NOTES</TH> 113168515Sgshapiro<TD>This function allows a milter to dynamically determine and 114168515Sgshapirorequest operations and actions during startup. 115168515SgshapiroIn previous versions, the actions (f0) were fixed in the 116168515Sgshapiro<A HREF="smfi_register.html#flags">flags</A> field of the 117168515Sgshapiro<A HREF="smfi_register.html#smfiDesc">smfiDesc</A> 118168515Sgshapirostructure 119168515Sgshapiroand the protocol steps (f1) were implicitly derived by checking whether 120168515Sgshapiroa callback was defined. 121168515SgshapiroDue to the extensions in the new milter version, 122168515Sgshapirosuch a static selection will not work if a milter requires 123168515Sgshapironew actions that are not available when talking to an older MTA. 124168515SgshapiroHence in the negotiation callback a milter can determine 125168515Sgshapirowhich operations are available and dynamically select 126168515Sgshapirothose which it needs and which are offered. 127168515SgshapiroIf some operations are not available, the milter may either fall back 128168515Sgshapiroto an older mode or abort the session and ask the user to upgrade. 129168515Sgshapiro 130168515Sgshapiro<!-- 131168515Sgshapiro<P> 132168515SgshapiroThe protocol steps are defined in 133168515Sgshapiro<CODE>include/libmilter/mfdef.h</CODE>: 134168515Sgshapirothe macros start with 135168515Sgshapiro<CODE>SMFIP_</CODE>. 136168515Sgshapiro--> 137168515Sgshapiro 138168515Sgshapiro<P> 139168515SgshapiroProtocol steps 140168515Sgshapiro(<CODE>f1</CODE>, <CODE>*pf1</CODE>): 141168515Sgshapiro<UL> 142168515Sgshapiro<LI><A NAME="SMFIP_RCPT_REJ"><CODE>SMFIP_RCPT_REJ</CODE></A>: 143168515SgshapiroBy setting this bit, a milter can request that the 144168515SgshapiroMTA should also send <CODE>RCPT</CODE> commands that have been rejected 145168515Sgshapirobecause the user is unknown (or similar reasons), but not those 146168515Sgshapirowhich have been rejected because of syntax errors etc. 147363466Sgshapiro<!-- 148363466SgshapiroIn order for this request to have effect, 149363466Sgshapirosendmail must have been built with the compile time option 150363466Sgshapiro<TT>_FFR_MILTER_CHECK_REJECTIONS_TOO</TT>. 151363466Sgshapiro--> 152168515SgshapiroIf a milter requests this protocol step, 153168515Sgshapirothen it should check the macro 154168515Sgshapiro<CODE>{rcpt_mailer}</CODE>: 155168515Sgshapiroif that is set to 156168515Sgshapiro<CODE>error</CODE>, 157168515Sgshapirothen the recipient will be rejected by the MTA. 158168515SgshapiroUsually the macros 159168515Sgshapiro<CODE>{rcpt_host}</CODE> and <CODE>{rcpt_addr}</CODE> 160168515Sgshapirowill contain an enhanced status code and an error text 161168515Sgshapiroin that case, respectively. 162168515Sgshapiro 163168515Sgshapiro<LI><A NAME="SMFIP_SKIP"><CODE>SMFIP_SKIP</CODE></A> 164168515Sgshapiroindicates that the MTA understand the 165168515Sgshapiro<A HREF="api.html#SMFIS_SKIP">SMFIS_SKIP</A> 166168515Sgshapiroreturn code. 167168515Sgshapiro 168168515Sgshapiro<LI><A NAME="SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A> 169168515Sgshapiroindicates that the MTA understand the 170168515Sgshapiro<A HREF="api.html#SMFIS_NOREPLY">SMFIS_NOREPLY</A> 171168515Sgshapiroreturn code. 172168515SgshapiroThere are flags for various protocol stages: 173168515Sgshapiro 174168515Sgshapiro<UL> 175168515Sgshapiro 176168515Sgshapiro<LI><A NAME="SMFIP_NR_CONN"><CODE>SMFIP_NR_CONN</CODE></A>: 177168515Sgshapiro<A HREF="xxfi_connect.html">xxfi_connect()</A> 178168515Sgshapiro 179168515Sgshapiro<LI><A NAME="SMFIP_NR_HELO"><CODE>SMFIP_NR_HELO</CODE></A>: 180168515Sgshapiro<A HREF="xxfi_helo.html">xxfi_helo()</A> 181168515Sgshapiro 182168515Sgshapiro<LI><A NAME="SMFIP_NR_MAIL"><CODE>SMFIP_NR_MAIL</CODE></A>: 183168515Sgshapiro<A HREF="xxfi_envfrom.html">xxfi_envfrom()</A> 184168515Sgshapiro 185168515Sgshapiro<LI><A NAME="SMFIP_NR_RCPT"><CODE>SMFIP_NR_RCPT</CODE></A>: 186168515Sgshapiro<A HREF="xxfi_envrcpt.html">xxfi_envrcpt()</A> 187168515Sgshapiro 188168515Sgshapiro<LI><A NAME="SMFIP_NR_DATA"><CODE>SMFIP_NR_DATA</CODE></A>: 189168515Sgshapiro<A HREF="xxfi_data.html">xxfi_data()</A> 190168515Sgshapiro 191168515Sgshapiro<LI><A NAME="SMFIP_NR_UNKN"><CODE>SMFIP_NR_UNKN</CODE></A>: 192168515Sgshapiro<A HREF="xxfi_unknown.html">xxfi_unknown()</A> 193168515Sgshapiro 194168515Sgshapiro<LI><A NAME="SMFIP_NR_EOH"><CODE>SMFIP_NR_EOH</CODE></A>: 195168515Sgshapiro<A HREF="xxfi_eoh.html">xxfi_eoh()</A> 196168515Sgshapiro 197168515Sgshapiro<LI><A NAME="SMFIP_NR_BODY"><CODE>SMFIP_NR_BODY</CODE></A>: 198168515Sgshapiro<A HREF="xxfi_body.html">xxfi_body()</A> 199168515Sgshapiro 200168515Sgshapiro<LI><A NAME="SMFIP_NR_HDR"><CODE>SMFIP_NR_HDR</CODE></A>: 201168515Sgshapiro<A HREF="xxfi_header.html">xxfi_header()</A> 202168515Sgshapiro 203168515Sgshapiro</UL> 204168515Sgshapiro 205168515Sgshapiro<LI><A NAME="SMFIP_HDR_LEADSPC"><CODE>SMFIP_HDR_LEADSPC</CODE></A> 206168515Sgshapiroindicates that the MTA can send header values with leading space intact. 207168515SgshapiroIf this protocol step is requested, then the MTA will also not add a leading 208168515Sgshapirospace to headers when they are added, inserted, or changed. 209168515Sgshapiro 210168515Sgshapiro<!-- 211168515Sgshapiro:'a,.s;^#define \(SMFIP_NO[A-Z]*\)[ ].*;<LI><A NAME="\1"><CODE>\1</CODE></A>:; 212168515Sgshapiro--> 213168515Sgshapiro<LI>The MTA can be instructed not to send information about 214168515Sgshapirovarious SMTP stages, these flags start with: 215168515Sgshapiro<A NAME="SMFIP_NO"><CODE>SMFIP_NO*</CODE></A>. 216363466SgshapiroSetting any of these flags affects all connections. 217168515Sgshapiro<UL> 218168515Sgshapiro<LI><A NAME="SMFIP_NOCONNECT"><CODE>SMFIP_NOCONNECT</CODE></A>: 219168515Sgshapiro<A HREF="xxfi_connect.html">xxfi_connect()</A> 220168515Sgshapiro<LI><A NAME="SMFIP_NOHELO"><CODE>SMFIP_NOHELO</CODE></A>: 221363466Sgshapiro<A HREF="xxfi_helo.html">xxfi_helo()</A> 222168515Sgshapiro<LI><A NAME="SMFIP_NOMAIL"><CODE>SMFIP_NOMAIL</CODE></A>: 223168515Sgshapiro<A HREF="xxfi_envfrom.html">xxfi_envfrom()</A> 224168515Sgshapiro<LI><A NAME="SMFIP_NORCPT"><CODE>SMFIP_NORCPT</CODE></A>: 225168515Sgshapiro<A HREF="xxfi_envrcpt.html">xxfi_envrcpt()</A> 226168515Sgshapiro<LI><A NAME="SMFIP_NOBODY"><CODE>SMFIP_NOBODY</CODE></A>: 227168515Sgshapiro<A HREF="xxfi_body.html">xxfi_body()</A> 228168515Sgshapiro<LI><A NAME="SMFIP_NOHDRS"><CODE>SMFIP_NOHDRS</CODE></A>: 229168515Sgshapiro<A HREF="xxfi_header.html">xxfi_header()</A> 230168515Sgshapiro<LI><A NAME="SMFIP_NOEOH"><CODE>SMFIP_NOEOH</CODE></A>: 231168515Sgshapiro<A HREF="xxfi_eoh.html">xxfi_eoh()</A> 232168515Sgshapiro<LI><A NAME="SMFIP_NOUNKNOWN"><CODE>SMFIP_NOUNKNOWN</CODE></A>: 233168515Sgshapiro<A HREF="xxfi_unknown.html">xxfi_unknown()</A> 234168515Sgshapiro<LI><A NAME="SMFIP_NODATA"><CODE>SMFIP_NODATA</CODE></A>: 235168515Sgshapiro<A HREF="xxfi_data.html">xxfi_data()</A> 236168515Sgshapiro</UL> 237168515Sgshapiro 238168515SgshapiroFor each of these xxfi_* callbacks that a milter does not use 239168515Sgshapirothe corresponding flag <EM>should</EM> be set in 240168515Sgshapiro<CODE>*pf1</CODE>. 241168515Sgshapiro 242168515Sgshapiro</UL> 243168515Sgshapiro 244168515Sgshapiro<P> 245168515SgshapiroThe available actions 246168515Sgshapiro(<CODE>f0</CODE>, <CODE>*pf0</CODE>) 247168515Sgshapiroare 248168515Sgshapiro<!-- 249168515Sgshapirodefined in 250168515Sgshapiro<CODE>include/libmilter/mfapi.h</CODE>: 251168515Sgshapirothe macros start with 252168515Sgshapiro<CODE>SMFIF_</CODE>; 253168515Sgshapirothese are 254168515Sgshapiro--> 255168515Sgshapirodescribed 256168515Sgshapiro<A HREF="smfi_register.html#flags">elsewhere (xxfi_flags)</A>. 257168515Sgshapiro 258168515Sgshapiro<P> 259168515SgshapiroIf a milter returns SMFIS_CONTINUE, then it <EM>must</EM> 260168515Sgshapiroset the desired actions and protocol steps 261168515Sgshapirovia the (output) parameters 262168515Sgshapiro<CODE>pf0</CODE> 263168515Sgshapiroand 264168515Sgshapiro<CODE>pf1</CODE> 265168515Sgshapiro(which correspond to 266168515Sgshapiro<CODE>f0</CODE> 267168515Sgshapiroand 268168515Sgshapiro<CODE>f1</CODE>, respectively). 269168515SgshapiroThe (output) parameters 270168515Sgshapiro<CODE>pf2</CODE> and 271168515Sgshapiro<CODE>pf3</CODE> 272168515Sgshapiroshould be set to 0 for compatibility with future versions. 273168515Sgshapiro 274168515Sgshapiro</TD> 275168515Sgshapiro</TR> 276168515Sgshapiro</TABLE> 277168515Sgshapiro 278168515Sgshapiro<HR size="1"> 279168515Sgshapiro<FONT size="-1"> 280261194SgshapiroCopyright (c) 2006 Proofpoint, Inc. and its suppliers. 281168515SgshapiroAll rights reserved. 282168515Sgshapiro<BR> 283168515SgshapiroBy using this file, you agree to the terms and conditions set 284168515Sgshapiroforth in the LICENSE. 285168515Sgshapiro</FONT> 286168515Sgshapiro</BODY> 287168515Sgshapiro</HTML> 288