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