xxfi_negotiate.html revision 168516 
152419Sjulian<HTML>
252419Sjulian<HEAD><TITLE>xxfi_negotiate</TITLE></HEAD>
352419Sjulian<BODY>
452419Sjulian<!--
552419Sjulian$Id: xxfi_negotiate.html,v 1.23 2006/12/20 18:57:08 ca Exp $
652419Sjulian-->
752419Sjulian<H1>xxfi_negotiate</H1>
852419Sjulian
952419Sjulian<TABLE border="0" cellspacing=4 cellpadding=4>
1052419Sjulian<!---------- Synopsis ----------->
1152419Sjulian<TR><TH valign="top" align=left width=100>SYNOPSIS</TH><TD>
1252419Sjulian<PRE>
1352419Sjulian#include &lt;libmilter/mfapi.h&gt;
1452419Sjulian#include &lt;libmilter/mfdef.h&gt;
1552419Sjuliansfsistat (*xxfi_negotiate)(
1652419Sjulian        SMFICTX    *ctx, 
1752419Sjulian	unsigned long f0,
1852419Sjulian	unsigned long f1,
1952419Sjulian	unsigned long f2,
2052419Sjulian	unsigned long f3,
2152419Sjulian	unsigned long *pf0,
2252419Sjulian	unsigned long *pf1,
2352419Sjulian	unsigned long *pf2,
2452419Sjulian	unsigned long *pf3);
2552419Sjulian</PRE>
2652419Sjulian</TD></TR>
2752419Sjulian<!----------- Description ---------->
2852419Sjulian<TR><TH valign="top" align=left>DESCRIPTION</TH><TD>
2952419Sjulian<TABLE border="1" cellspacing=1 cellpadding=4>
3052419Sjulian<TR>
3152419Sjulian<TH valign="top" align=left width=80>Called When</TH>
3252419Sjulian<TD>Once, at the start of each SMTP connection.</TD>
3352419Sjulian</TR>
3452419Sjulian<TR>
3552419Sjulian<TH valign="top" align=left width=80>Default Behavior</TH>
3652419Sjulian<TD>Return SMFIS_ALL_OPTS to change nothing.</TD>
3752419Sjulian</TR>
3852419Sjulian</TABLE>
3952419Sjulian<!----------- Arguments ---------->
4052419Sjulian<TR><TH valign="top" align=left>ARGUMENTS</TH><TD>
4152419Sjulian    <TABLE border="1" cellspacing=0>
4252419Sjulian    <TR bgcolor="#dddddd"><TH>Argument</TH><TH>Description</TH></TR>
4352419Sjulian    <TR><TD>ctx</TD>
4452419Sjulian	<TD>the opaque context structure.
4552419Sjulian	</TD></TR>
4652419Sjulian    <TR><TD>f0</TD>
4752419Sjulian	<TD>the actions offered by the MTA.
4852419Sjulian	</TD></TR>
4952419Sjulian    <TR><TD>f1</TD>
5052419Sjulian	<TD>the protocol steps offered by the MTA.
5152419Sjulian    <TR><TD>f2</TD>
5252419Sjulian	<TD>for future extensions.
5352419Sjulian	</TD></TR>
5452419Sjulian    <TR><TD>f3</TD>
5552419Sjulian	<TD>for future extensions.
5652419Sjulian	</TD></TR>
5752419Sjulian    <TR><TD>pf0</TD>
5852419Sjulian	<TD>the actions requested by the milter.
5952419Sjulian	</TD></TR>
6052419Sjulian    <TR><TD>pf1</TD>
6152419Sjulian	<TD>the protocol steps requested by the milter.
6252419Sjulian    <TR><TD>pf2</TD>
6352419Sjulian	<TD>for future extensions.
6452419Sjulian	</TD></TR>
6552419Sjulian    <TR><TD>pf3</TD>
6652419Sjulian	<TD>for future extensions.
6752419Sjulian	</TD></TR>
6852419Sjulian    </TABLE>
6952419Sjulian</TD></TR>
7052419Sjulian
7152419Sjulian<!----------- Return values ---------->
7252419Sjulian<TR>
7352419Sjulian<TH valign="top" align=left>SPECIAL RETURN VALUES</TH>
7452419Sjulian<TD><TABLE border="1" cellspacing=0>
7552419Sjulian  <TR bgcolor="#dddddd"><TH>Return value</TH><TH>Description</TH></TR>
7652419Sjulian  <TR valign="top">
7752419Sjulian     <TD>SMFIS_ALL_OPTS</TD>
7852419Sjulian     <TD>
7952419SjulianIf a milter just wants to inspect the available protocol steps
8052419Sjulianand actions, then it can return
8152419SjulianSMFIS_ALL_OPTS
8252419Sjulianand the MTA will make all protocol steps and actions available
8352419Sjulianto the milter.
8452419SjulianIn this case, no values should be assigned to the output parameters
8552419Sjulian<CODE>pf0</CODE> - <CODE>pf3</CODE>
8652419Sjulianas they will be ignored.
8752419Sjulian     </TD>
8852419Sjulian  </TR>
8952419Sjulian  <TR valign="top">
9052419Sjulian     <TD>SMFIS_REJECT</TD>
9152419Sjulian     <TD>Milter startup fails and it will not be contacted again
9252419Sjulian(for the current connection).
9352419Sjulian     </TD>
9452419Sjulian  </TR>
9552419Sjulian  <TR valign="top">
9652419Sjulian     <TD>SMFIS_CONTINUE</TD>
9752419Sjulian     <TD>Continue processing.
9852419Sjulian	In this case the milter <EM>must</EM> set all output parameters
9952419Sjulian	<CODE>pf0</CODE> - <CODE>pf3</CODE>.
10052419Sjulian	See below for an explanation how to set those output parameters.
10152419Sjulian     </TD>
10252419Sjulian  </TR>
10352419Sjulian</TABLE>
10452419Sjulian</TR>
10552419Sjulian
10652419Sjulian<!----------- Notes ---------->
10752419Sjulian<TR>
10852419Sjulian<TH valign="top" align=left>NOTES</TH> 
10952419Sjulian<TD>This function allows a milter to dynamically determine and
11052419Sjulianrequest operations and actions during startup.
11152419SjulianIn previous versions, the actions (f0) were fixed in the
11252419Sjulian<A HREF="smfi_register.html#flags">flags</A> field of the
11352419Sjulian<A HREF="smfi_register.html#smfiDesc">smfiDesc</A>
11452419Sjulianstructure
11552419Sjulianand the protocol steps (f1) were implicitly derived by checking whether
11652419Sjuliana callback was defined.
11752419SjulianDue to the extensions in the new milter version,
11852419Sjuliansuch a static selection will not work if a milter requires
11952419Sjuliannew actions that are not available when talking to an older MTA.
12052419SjulianHence in the negotiation callback a milter can determine
12152419Sjulianwhich operations are available and dynamically select
12252419Sjulianthose which it needs and which are offered.
12352419SjulianIf some operations are not available, the milter may either fall back
12452419Sjulianto an older mode or abort the session and ask the user to upgrade.
12552419Sjulian
12652419Sjulian<!--
12752419Sjulian<P>
12852419SjulianThe protocol steps are defined in
12952419Sjulian<CODE>include/libmilter/mfdef.h</CODE>:
13052419Sjulianthe macros start with
13152419Sjulian<CODE>SMFIP_</CODE>.
13252419Sjulian-->
13352419Sjulian
13452419Sjulian<P>
13552419SjulianProtocol steps
13652419Sjulian(<CODE>f1</CODE>, <CODE>*pf1</CODE>):
13752419Sjulian<UL>
13852419Sjulian<LI><A NAME="SMFIP_RCPT_REJ"><CODE>SMFIP_RCPT_REJ</CODE></A>:
13952419SjulianBy setting this bit, a milter can request that the
14052419SjulianMTA should also send <CODE>RCPT</CODE> commands that have been rejected
14152419Sjulianbecause the user is unknown (or similar reasons), but not those
14252419Sjulianwhich have been rejected because of syntax errors etc.
14352419SjulianIf a milter requests this protocol step,
14452419Sjulianthen it should check the macro
14552419Sjulian<CODE>{rcpt_mailer}</CODE>:
14652419Sjulianif that is set to
14752419Sjulian<CODE>error</CODE>,
14852419Sjulianthen the recipient will be rejected by the MTA.
14952419SjulianUsually the macros
15052419Sjulian<CODE>{rcpt_host}</CODE> and <CODE>{rcpt_addr}</CODE>
15152419Sjulianwill contain an enhanced status code and an error text
15252419Sjulianin that case, respectively.
15352419Sjulian
15452419Sjulian<LI><A NAME="SMFIP_SKIP"><CODE>SMFIP_SKIP</CODE></A>
15552419Sjulianindicates that the MTA understand the
15652419Sjulian<A HREF="api.html#SMFIS_SKIP">SMFIS_SKIP</A>
15752419Sjulianreturn code.
15852419Sjulian
15952419Sjulian<LI><A NAME="SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
16052419Sjulianindicates that the MTA understand the
16152419Sjulian<A HREF="api.html#SMFIS_NOREPLY">SMFIS_NOREPLY</A>
16252419Sjulianreturn code.
16352419SjulianThere are flags for various protocol stages:
16452419Sjulian
16552419Sjulian<UL>
16652419Sjulian
16752419Sjulian<LI><A NAME="SMFIP_NR_CONN"><CODE>SMFIP_NR_CONN</CODE></A>:
16852419Sjulian<A HREF="xxfi_connect.html">xxfi_connect()</A>
16952419Sjulian
17052419Sjulian<LI><A NAME="SMFIP_NR_HELO"><CODE>SMFIP_NR_HELO</CODE></A>:
17152419Sjulian<A HREF="xxfi_helo.html">xxfi_helo()</A>
17252419Sjulian
17352419Sjulian<LI><A NAME="SMFIP_NR_MAIL"><CODE>SMFIP_NR_MAIL</CODE></A>:
17452419Sjulian<A HREF="xxfi_envfrom.html">xxfi_envfrom()</A>
17552419Sjulian
17652419Sjulian<LI><A NAME="SMFIP_NR_RCPT"><CODE>SMFIP_NR_RCPT</CODE></A>:
17752419Sjulian<A HREF="xxfi_envrcpt.html">xxfi_envrcpt()</A>
17852419Sjulian
17952419Sjulian<LI><A NAME="SMFIP_NR_DATA"><CODE>SMFIP_NR_DATA</CODE></A>:
18052419Sjulian<A HREF="xxfi_data.html">xxfi_data()</A>
18152419Sjulian
18252419Sjulian<LI><A NAME="SMFIP_NR_UNKN"><CODE>SMFIP_NR_UNKN</CODE></A>:
18352419Sjulian<A HREF="xxfi_unknown.html">xxfi_unknown()</A>
18452419Sjulian
18552419Sjulian<LI><A NAME="SMFIP_NR_EOH"><CODE>SMFIP_NR_EOH</CODE></A>:
18652419Sjulian<A HREF="xxfi_eoh.html">xxfi_eoh()</A>
18752419Sjulian
18852419Sjulian<LI><A NAME="SMFIP_NR_BODY"><CODE>SMFIP_NR_BODY</CODE></A>:
18952419Sjulian<A HREF="xxfi_body.html">xxfi_body()</A>
19052419Sjulian
19152419Sjulian<LI><A NAME="SMFIP_NR_HDR"><CODE>SMFIP_NR_HDR</CODE></A>:
19252419Sjulian<A HREF="xxfi_header.html">xxfi_header()</A>
19352419Sjulian
19452419Sjulian</UL>
19552419Sjulian
19652419Sjulian<LI><A NAME="SMFIP_HDR_LEADSPC"><CODE>SMFIP_HDR_LEADSPC</CODE></A>
19752419Sjulianindicates that the MTA can send header values with leading space intact.
19852419SjulianIf this protocol step is requested, then the MTA will also not add a leading
19952419Sjulianspace to headers when they are added, inserted, or changed.
20052419Sjulian
20152419Sjulian<!--
20252419Sjulian:'a,.s;^#define \(SMFIP_NO[A-Z]*\)[ 	].*;<LI><A NAME="\1"><CODE>\1</CODE></A>:;
20352419Sjulian-->
20452419Sjulian<LI>The MTA can be instructed not to send information about
20552419Sjulianvarious SMTP stages, these flags start with:
20652419Sjulian<A NAME="SMFIP_NO"><CODE>SMFIP_NO*</CODE></A>.
20752419Sjulian<UL>
20852419Sjulian<LI><A NAME="SMFIP_NOCONNECT"><CODE>SMFIP_NOCONNECT</CODE></A>:
20952419Sjulian<A HREF="xxfi_connect.html">xxfi_connect()</A>
21052419Sjulian<LI><A NAME="SMFIP_NOHELO"><CODE>SMFIP_NOHELO</CODE></A>:
21152419Sjulian<A HREF="xxfi_header.html">xxfi_header()</A>
21252419Sjulian<LI><A NAME="SMFIP_NOMAIL"><CODE>SMFIP_NOMAIL</CODE></A>:
21352419Sjulian<A HREF="xxfi_envfrom.html">xxfi_envfrom()</A>
21452419Sjulian<LI><A NAME="SMFIP_NORCPT"><CODE>SMFIP_NORCPT</CODE></A>:
21552419Sjulian<A HREF="xxfi_envrcpt.html">xxfi_envrcpt()</A>
21652419Sjulian<LI><A NAME="SMFIP_NOBODY"><CODE>SMFIP_NOBODY</CODE></A>:
21752419Sjulian<A HREF="xxfi_body.html">xxfi_body()</A>
21852419Sjulian<LI><A NAME="SMFIP_NOHDRS"><CODE>SMFIP_NOHDRS</CODE></A>:
21952419Sjulian<A HREF="xxfi_header.html">xxfi_header()</A>
22052419Sjulian<LI><A NAME="SMFIP_NOEOH"><CODE>SMFIP_NOEOH</CODE></A>:
22152419Sjulian<A HREF="xxfi_eoh.html">xxfi_eoh()</A>
22252419Sjulian<LI><A NAME="SMFIP_NOUNKNOWN"><CODE>SMFIP_NOUNKNOWN</CODE></A>:
22352419Sjulian<A HREF="xxfi_unknown.html">xxfi_unknown()</A>
22452419Sjulian<LI><A NAME="SMFIP_NODATA"><CODE>SMFIP_NODATA</CODE></A>:
225<A HREF="xxfi_data.html">xxfi_data()</A>
226</UL>
227
228For each of these xxfi_* callbacks that a milter does not use
229the corresponding flag <EM>should</EM> be set in
230<CODE>*pf1</CODE>.
231
232</UL>
233
234<P>
235The available actions
236(<CODE>f0</CODE>, <CODE>*pf0</CODE>)
237are
238<!--
239defined in
240<CODE>include/libmilter/mfapi.h</CODE>:
241the macros start with
242<CODE>SMFIF_</CODE>;
243these are
244-->
245described
246<A HREF="smfi_register.html#flags">elsewhere (xxfi_flags)</A>.
247
248<P>
249If a milter returns SMFIS_CONTINUE, then it <EM>must</EM>
250set the desired actions and protocol steps
251via the (output) parameters
252<CODE>pf0</CODE>
253and
254<CODE>pf1</CODE>
255(which correspond to
256<CODE>f0</CODE>
257and
258<CODE>f1</CODE>, respectively).
259The (output) parameters
260<CODE>pf2</CODE> and
261<CODE>pf3</CODE>
262should be set to 0 for compatibility with future versions.
263
264</TD>
265</TR>
266</TABLE>
267
268<HR size="1">
269<FONT size="-1">
270Copyright (c) 2006 Sendmail, Inc. and its suppliers.
271All rights reserved.
272<BR>
273By using this file, you agree to the terms and conditions set
274forth in the LICENSE.
275</FONT>
276</BODY>
277</HTML>
278