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