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
|
<html>
<head><title>Milter API</title></head>
<body>
<h1>Milter API</h1>
<h2>Contents</h2>
<ul>
<li>Library Control Functions
<li>Data Access Functions
<li>Message Modification Functions
<li>Callbacks
</ul>
<h2>Library Control Functions</h2>
Before handing control to libmilter (by calling <a
href="smfi_main.html">smfi_main</a>), a filter may call the following
functions to set libmilter parameters. In particular, the filter must
call <a href="smfi_register.html">smfi_register</a> to register its
callbacks. Each function will return either MI_SUCCESS or MI_FAILURE to
indicate the status of the operation.
<p>
None of these functions communicate with the MTA. All alter the
library's state, some of which is communicated to the MTA inside <a
href="smfi_main.html">smfi_main</a>.
<p>
<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr>
<tr><td><a href="smfi_register.html">smfi_register</a></td><td>Register a filter.</td></tr>
<tr><td><a href="smfi_setconn.html">smfi_setconn</a></td><td>Specify socket to use.</td></tr>
<tr><td><a href="smfi_settimeout.html">smfi_settimeout</a></td><td>Set timeout.</td></tr>
<tr><td><a href="smfi_main.html">smfi_main</a></td><td>Hand control to libmilter.</td></tr>
</table>
<h2>Data Access Functions</h2>
The following functions may be called from within the filter-defined callbacks
to access information about the current connection or message.
<p>
<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr>
<tr><td><a href="smfi_getsymval.html">smfi_getsymval</a></td><td>Return the value
of a symbol.</td></tr>
<tr><td><a href="smfi_getpriv.html">smfi_getpriv</a></td><td>Get the private data
pointer.</td></tr>
<tr><td><a href="smfi_setpriv.html">smfi_setpriv</a></td><td>Set the private data
pointer.</td></tr>
<tr><td><a href="smfi_setreply.html">smfi_setreply</a></td><td>Set the specific
reply code to be used.</td></tr>
</table>
<h2>Message Modification Functions</h2>
The following functions change a message's contents and attributes.
<b>They may only be called in <a href="xxfi_eom.html">xxfi_eom</a></b>.
All of these functions may invoke additional communication with the MTA.
They will return either MI_SUCCESS or MI_FAILURE to indicate the status of
the operation.
<p>
A filter must have set the appropriate flag (listed below) in the
description passed to <a href="smfi_register.html">smfi_register</a>
to call any message modification function. Failure to do so will
cause the MTA to treat a call to the function as a failure of the
filter, terminating its connection.
<p>
Note that the status returned indicates only whether or not the
filter's message was successfully sent to the MTA, not whether or not
the MTA performed the requested operation. For example, <a
href="smfi_addheader.html">smfi_addheader</a>, when called with an
illegal header name, will return MI_SUCCESS even though the MTA may
later refuse to add the illegal header.
<p>
<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th><th>SMFIF_* flag</tr>
<tr><td><a href="smfi_addheader.html">smfi_addheader</a></td><td>Add a header to
the message.</td><td>SMFIF_ADDHDRS</td></tr>
<tr><td><a href="smfi_chgheader.html">smfi_chgheader</a></td><td>Change or delete a header.</td><td>SMFIF_CHGHDRS</td></tr>
<tr><td><a href="smfi_addrcpt.html">smfi_addrcpt</a></td><td>Add a recipient to
the envelope.</td><td>SMFIF_ADDRCPT</td></tr>
<tr><td><a href="smfi_delrcpt.html">smfi_delrcpt</a></td><td>Delete a recipient
from the envelope.</td><td>SMFIF_DELRCPT</td></tr>
<tr><td><a href="smfi_replacebody.html">smfi_replacebody</a></td><td>Replace the
body of the message.</td><td>SMFIF_CHGBODY</td></tr>
</table>
<h2>Callbacks</h2>
The filter should implement one or more of the following callbacks,
which are registered via <a href="smfi_register.html">smfi_register</a>:
<p>
<table border="1" cellspacing=0 cellpadding=2><tr bgcolor="#dddddd"><th>Function</th><th>Description</th></tr>
<tr><td><a href="xxfi_connect.html">xxfi_connect</a></td><td>connection info</td></tr>
<tr><td><a href="xxfi_helo.html">xxfi_helo</a></td><td>SMTP HELO/EHLO command</td></tr>
<tr><td><a href="xxfi_envfrom.html">xxfi_envfrom</a></td><td>envelope sender</td></tr>
<tr><td><a href="xxfi_envrcpt.html">xxfi_envrcpt</a></td><td>envelope recipient</td></tr>
<tr><td><a href="xxfi_header.html">xxfi_header</a></td><td>header</td></tr>
<tr><td><a href="xxfi_eoh.html">xxfi_eoh</a></td><td>end of header</td></tr>
<tr><td><a href="xxfi_body.html">xxfi_body</a></td><td>body block</td></tr>
<tr><td><a href="xxfi_eom.html">xxfi_eom</a></td><td>end of message</td></tr>
<tr><td><a href="xxfi_abort.html">xxfi_abort</a></td><td>message aborted</td></tr>
<tr><td><a href="xxfi_close.html">xxfi_close</a></td><td>connection cleanup</td></tr>
</table>
<p>
The above callbacks should all return one of the following return values,
having the indicated meanings. Any return other than one of the below
values constitutes an error, and will cause sendmail to terminate its
connection to the offending filter.
<p><a name="conn-spec"></a>Milter distinguishes between recipient-,
message-, and connection-oriented routines. Recipient-oriented
callbacks may affect the processing of a single message recipient;
message-oriented callbacks, a single message; connection-oriented
callbacks, an entire connection (during which multiple messages may be
delivered to multiple sets of recipients).
<a href="xxfi_envrcpt.html">xxfi_envrcpt</a> is recipient-oriented.
<a href="xxfi_connect.html">xxfi_connect</a>,
<a href="xxfi_helo.html">xxfi_helo</a> and
<a href="xxfi_close.html">xxfi_close</a> are connection-oriented. All
other callbacks are message-oriented.
<p>
<table border="1" cellspacing=0 cellpadding=2>
<tr bgcolor="#dddddd"><th>Return value</th><th>Description</th></tr>
<tr valign="top">
<td>SMFIS_CONTINUE</td>
<td>Continue processing the current connection, message, or recipient.
</td>
</tr>
<tr valign="top">
<td>SMFIS_REJECT</td>
<td>For a connection-oriented routine, reject this connection; call <a href="xxfi_close.html">xxfi_close</a>.<br>
For a message-oriented routine (except
<a href="xxfi_eom.html">xxfi_eom</a> or
<a href="xxfi_abort.html">xxfi_abort</a>), reject this message.<br>
For a recipient-oriented routine, reject the current recipient (but continue processing the current message).
</td>
</tr>
<tr valign="top">
<td>SMFIS_DISCARD</td>
<td>For a message- or recipient-oriented routine, accept this message, but silently discard it.<br>
SMFIS_DISCARD should not be returned by a connection-oriented routine.
</td>
</tr>
<tr valign="top">
<td>SMFIS_ACCEPT</td>
<td>For a connection-oriented routine, accept this connection without further filter processing; call <a href="xxfi_close.html">xxfi_close</a>.<br>
For a message- or recipient-oriented routine, accept this message without further filtering.<br>
</td>
</tr>
<tr valign="top">
<td>SMFIS_TEMPFAIL</td>
<td>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code.
For a message-oriented routine (except <a href="xxfi_envfrom.html">xxfi_envfrom</a>), fail for this message. <br>
For a connection-oriented routine, fail for this connection; call <a href="xxfi_close.html">xxfi_close</a>. <br>
For a recipient-oriented routine, only fail for the current recipient; continue message processing.
</td>
</tr>
</table>
<hr size="1">
<font size="-1">
Copyright (c) 2000 Sendmail, Inc. and its suppliers.
All rights reserved.
<br>
By using this file, you agree to the terms and conditions set
forth in the <a href="LICENSE.txt">LICENSE</a>.
</font>
</body>
</html>
|
