2 <HEAD><TITLE>xxfi_negotiate</TITLE></HEAD>
5 $Id: xxfi_negotiate.html,v 1.23 2006/12/20 18:57:08 ca Exp $
7 <H1>xxfi_negotiate</H1>
9 <TABLE border="0" cellspacing=4 cellpadding=4>
10 <!---------- Synopsis ----------->
11 <TR><TH valign="top" align=left width=100>SYNOPSIS</TH><TD>
13 #include <libmilter/mfapi.h>
14 #include <libmilter/mfdef.h>
15 sfsistat (*xxfi_negotiate)(
27 <!----------- Description ---------->
28 <TR><TH valign="top" align=left>DESCRIPTION</TH><TD>
29 <TABLE border="1" cellspacing=1 cellpadding=4>
31 <TH valign="top" align=left width=80>Called When</TH>
32 <TD>Once, at the start of each SMTP connection.</TD>
35 <TH valign="top" align=left width=80>Default Behavior</TH>
36 <TD>Return SMFIS_ALL_OPTS to change nothing.</TD>
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>
44 <TD>the opaque context structure.
47 <TD>the actions offered by the MTA.
50 <TD>the protocol steps offered by the MTA.
52 <TD>for future extensions.
55 <TD>for future extensions.
58 <TD>the actions requested by the milter.
61 <TD>the protocol steps requested by the milter.
63 <TD>for future extensions.
66 <TD>for future extensions.
71 <!----------- Return values ---------->
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>
77 <TD>SMFIS_ALL_OPTS</TD>
79 If a milter just wants to inspect the available protocol steps
80 and actions, then it can return
82 and the MTA will make all protocol steps and actions available
84 In this case, no values should be assigned to the output parameters
85 <CODE>pf0</CODE> - <CODE>pf3</CODE>
86 as they will be ignored.
91 <TD>Milter startup fails and it will not be contacted again
92 (for the current connection).
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.
106 <!----------- Notes ---------->
108 <TH valign="top" align=left>NOTES</TH>
109 <TD>This function allows a milter to dynamically determine and
110 request operations and actions during startup.
111 In 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>
115 and the protocol steps (f1) were implicitly derived by checking whether
116 a callback was defined.
117 Due to the extensions in the new milter version,
118 such a static selection will not work if a milter requires
119 new actions that are not available when talking to an older MTA.
120 Hence in the negotiation callback a milter can determine
121 which operations are available and dynamically select
122 those which it needs and which are offered.
123 If some operations are not available, the milter may either fall back
124 to an older mode or abort the session and ask the user to upgrade.
128 The protocol steps are defined in
129 <CODE>include/libmilter/mfdef.h</CODE>:
130 the macros start with
136 (<CODE>f1</CODE>, <CODE>*pf1</CODE>):
138 <LI><A NAME="SMFIP_RCPT_REJ"><CODE>SMFIP_RCPT_REJ</CODE></A>:
139 By setting this bit, a milter can request that the
140 MTA should also send <CODE>RCPT</CODE> commands that have been rejected
141 because the user is unknown (or similar reasons), but not those
142 which have been rejected because of syntax errors etc.
143 If a milter requests this protocol step,
144 then it should check the macro
145 <CODE>{rcpt_mailer}</CODE>:
148 then the recipient will be rejected by the MTA.
150 <CODE>{rcpt_host}</CODE> and <CODE>{rcpt_addr}</CODE>
151 will contain an enhanced status code and an error text
152 in that case, respectively.
154 <LI><A NAME="SMFIP_SKIP"><CODE>SMFIP_SKIP</CODE></A>
155 indicates that the MTA understand the
156 <A HREF="api.html#SMFIS_SKIP">SMFIS_SKIP</A>
159 <LI><A NAME="SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
160 indicates that the MTA understand the
161 <A HREF="api.html#SMFIS_NOREPLY">SMFIS_NOREPLY</A>
163 There are flags for various protocol stages:
167 <LI><A NAME="SMFIP_NR_CONN"><CODE>SMFIP_NR_CONN</CODE></A>:
168 <A HREF="xxfi_connect.html">xxfi_connect()</A>
170 <LI><A NAME="SMFIP_NR_HELO"><CODE>SMFIP_NR_HELO</CODE></A>:
171 <A HREF="xxfi_helo.html">xxfi_helo()</A>
173 <LI><A NAME="SMFIP_NR_MAIL"><CODE>SMFIP_NR_MAIL</CODE></A>:
174 <A HREF="xxfi_envfrom.html">xxfi_envfrom()</A>
176 <LI><A NAME="SMFIP_NR_RCPT"><CODE>SMFIP_NR_RCPT</CODE></A>:
177 <A HREF="xxfi_envrcpt.html">xxfi_envrcpt()</A>
179 <LI><A NAME="SMFIP_NR_DATA"><CODE>SMFIP_NR_DATA</CODE></A>:
180 <A HREF="xxfi_data.html">xxfi_data()</A>
182 <LI><A NAME="SMFIP_NR_UNKN"><CODE>SMFIP_NR_UNKN</CODE></A>:
183 <A HREF="xxfi_unknown.html">xxfi_unknown()</A>
185 <LI><A NAME="SMFIP_NR_EOH"><CODE>SMFIP_NR_EOH</CODE></A>:
186 <A HREF="xxfi_eoh.html">xxfi_eoh()</A>
188 <LI><A NAME="SMFIP_NR_BODY"><CODE>SMFIP_NR_BODY</CODE></A>:
189 <A HREF="xxfi_body.html">xxfi_body()</A>
191 <LI><A NAME="SMFIP_NR_HDR"><CODE>SMFIP_NR_HDR</CODE></A>:
192 <A HREF="xxfi_header.html">xxfi_header()</A>
196 <LI><A NAME="SMFIP_HDR_LEADSPC"><CODE>SMFIP_HDR_LEADSPC</CODE></A>
197 indicates that the MTA can send header values with leading space intact.
198 If this protocol step is requested, then the MTA will also not add a leading
199 space to headers when they are added, inserted, or changed.
202 :'a,.s;^#define \(SMFIP_NO[A-Z]*\)[ ].*;<LI><A NAME="\1"><CODE>\1</CODE></A>:;
204 <LI>The MTA can be instructed not to send information about
205 various SMTP stages, these flags start with:
206 <A NAME="SMFIP_NO"><CODE>SMFIP_NO*</CODE></A>.
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>
228 For each of these xxfi_* callbacks that a milter does not use
229 the corresponding flag <EM>should</EM> be set in
235 The available actions
236 (<CODE>f0</CODE>, <CODE>*pf0</CODE>)
240 <CODE>include/libmilter/mfapi.h</CODE>:
241 the macros start with
246 <A HREF="smfi_register.html#flags">elsewhere (xxfi_flags)</A>.
249 If a milter returns SMFIS_CONTINUE, then it <EM>must</EM>
250 set the desired actions and protocol steps
251 via the (output) parameters
258 <CODE>f1</CODE>, respectively).
259 The (output) parameters
262 should be set to 0 for compatibility with future versions.
270 Copyright (c) 2006 Sendmail, Inc. and its suppliers.
273 By using this file, you agree to the terms and conditions set
274 forth in the LICENSE.