1<HTML>
2<HEAD><TITLE>Milter API</TITLE></HEAD>
3<BODY>
4<!--
5$Id: api.html,v 1.37 2009/05/19 00:40:52 ca Exp $
6-->
7<H1>Milter API</H1>
8
9<H2>Contents</H2>
10<UL>
11    <LI><A HREF="#LibraryControlFunctions">Library Control Functions</A>
12    <LI><A HREF="#DataAccessFunctions">Data Access Functions</A>
13    <LI><A HREF="#MessageModificationFunctions">Message Modification Functions</A>
14    <LI><A HREF="#Callbacks">Callbacks</A>
15    <LI><A HREF="#Miscellaneous">Miscellaneous</A>
16</UL>
17
18<H2><A NAME="LibraryControlFunctions">Library Control Functions</A></H2>
19
20Before handing control to libmilter (by calling
21<A HREF="smfi_main.html">smfi_main</A>), a filter may call the following
22functions to set libmilter parameters.
23In particular, the filter must call
24<A HREF="smfi_register.html">smfi_register</A> to register its callbacks.
25Each function will return either MI_SUCCESS or MI_FAILURE to
26indicate the status of the operation.
27
28<P>
29None of these functions communicate with the MTA.  All alter the
30library's state, some of which is communicated to the MTA inside
31<A HREF="smfi_main.html">smfi_main</A>.
32
33<P>
34<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
35
36<TR><TD><A HREF="smfi_opensocket.html">smfi_opensocket</A></TD><TD>Try to create the interface socket.</TD></TR>
37
38<TR><TD><A HREF="smfi_register.html">smfi_register</A></TD><TD>Register a filter.</TD></TR>
39
40<TR><TD><A HREF="smfi_setconn.html">smfi_setconn</A></TD><TD>Specify socket to use.</TD></TR>
41
42<TR><TD><A HREF="smfi_settimeout.html">smfi_settimeout</A></TD><TD>Set timeout.</TD></TR>
43
44<TR><TD><A HREF="smfi_setbacklog.html">smfi_setbacklog</A></TD><TD>Define the incoming <CODE>listen(2)</CODE> queue size.</TD></TR>
45
46<TR><TD><A HREF="smfi_setdbg.html">smfi_setdbg</A></TD><TD>Set the milter library debugging (tracing) level.</TD></TR>
47
48<TR><TD><A HREF="smfi_stop.html">smfi_stop</A></TD><TD>Cause an orderly shutdown.</TD></TR>
49
50<TR><TD><A HREF="smfi_main.html">smfi_main</A></TD><TD>Hand control to libmilter.</TD></TR>
51
52</TABLE>
53
54<H2><A NAME="DataAccessFunctions">Data Access Functions</A></H2>
55
56The following functions may be called from within the filter-defined callbacks
57to access information about the current connection or message.
58<P>
59<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR bgcolor="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
60<TR><TD><A HREF="smfi_getsymval.html">smfi_getsymval</A></TD><TD>Return the value
61of a symbol.</TD></TR>
62
63<TR><TD><A HREF="smfi_getpriv.html">smfi_getpriv</A></TD><TD>Get the private data
64pointer.</TD></TR>
65
66<TR><TD><A HREF="smfi_setpriv.html">smfi_setpriv</A></TD><TD>Set the private data
67pointer.</TD></TR>
68
69<TR><TD><A HREF="smfi_setreply.html">smfi_setreply</A></TD><TD>Set the specific
70reply code to be used.</TD></TR>
71
72<TR><TD><A HREF="smfi_setmlreply.html">smfi_setmlreply</A></TD><TD>Set the
73specific multi-line reply to be used.</TD></TR>
74
75</TABLE>
76
77<H2><A NAME="MessageModificationFunctions">Message Modification Functions</A></H2>
78
79The following functions change a message's contents and attributes.
80<EM>They may only be called in <A HREF="xxfi_eom.html">xxfi_eom</A></EM>.
81All of these functions may invoke additional communication with the MTA.
82They will return either MI_SUCCESS or MI_FAILURE to indicate the status of
83the operation.  Message data (senders, recipients, headers, body chunks)
84passed to these functions via parameters is copied and does not need to be
85preserved (i.e., allocated memory can be freed).
86
87<P>
88A filter must have set the appropriate flag (listed below) in the
89description passed to <A HREF="smfi_register.html">smfi_register</A>
90to call any message modification function.  Failure to do so will
91cause the MTA to treat a call to the function as a failure of the
92filter, terminating its connection.
93
94<P>
95Note that the status returned indicates only whether or not the
96filter's message was successfully sent to the MTA, not whether or not
97the MTA performed the requested operation.  For example,
98<A HREF="smfi_addheader.html">smfi_addheader</A>, when called with an
99illegal header name, will return MI_SUCCESS even though the MTA may
100later refuse to add the illegal header.
101<P>
102<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH><TH>SMFIF_* flag</TR>
103<TR><TD><A HREF="smfi_addheader.html">smfi_addheader</A></TD><TD>Add a header to
104the message.</TD><TD>SMFIF_ADDHDRS</TD></TR>
105
106<TR><TD><A HREF="smfi_chgheader.html">smfi_chgheader</A></TD><TD>Change or delete a header.</TD><TD>SMFIF_CHGHDRS</TD></TR>
107
108<TR><TD><A HREF="smfi_insheader.html">smfi_insheader</A></TD><TD>Insert a
109header into the message.</TD><TD>SMFIF_ADDHDRS</TD></TR>
110
111<TR><TD><A HREF="smfi_chgfrom.html">smfi_chgfrom</A></TD><TD>Change the
112envelope sender address.</TD><TD>SMFIF_CHGFROM</TD></TR>
113
114<TR><TD><A HREF="smfi_addrcpt.html">smfi_addrcpt</A></TD><TD>Add a recipient to
115the envelope.</TD><TD>SMFIF_ADDRCPT</TD></TR>
116
117<TR><TD><A HREF="smfi_addrcpt_par.html">smfi_addrcpt_par</A></TD><TD>Add
118a recipient including ESMTP parameter to the envelope.
119</TD><TD>SMFIF_ADDRCPT_PAR</TD></TR>
120
121<TR><TD><A HREF="smfi_delrcpt.html">smfi_delrcpt</A></TD><TD>Delete a recipient
122from the envelope.</TD><TD>SMFIF_DELRCPT</TD></TR>
123
124<TR><TD><A HREF="smfi_replacebody.html">smfi_replacebody</A></TD><TD>Replace the
125body of the message.</TD><TD>SMFIF_CHGBODY</TD></TR>
126
127</TABLE>
128
129<H2>Other Message Handling Functions</H2>
130
131The following functions provide special case handling instructions for
132milter or the MTA, without altering the content or status of the message.
133<EM>They too may only be called in <A HREF="xxfi_eom.html">xxfi_eom</A></EM>.
134All of these functions may invoke additional communication with the MTA.
135They will return either MI_SUCCESS or MI_FAILURE to indicate the status of
136the operation.
137
138<P>
139Note that the status returned indicates only whether or not the
140filter's message was successfully sent to the MTA, not whether or not
141the MTA performed the requested operation.
142
143<P>
144<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
145<TR><TD><A HREF="smfi_progress.html">smfi_progress</A></TD><TD>Report operation in progress.</TD></TR>
146
147<TR><TD><A HREF="smfi_quarantine.html">smfi_quarantine</A></TD><TD>Quarantine a message.</TD></TR>
148
149</TABLE>
150
151<H2><A NAME="Callbacks">Callbacks</A></H2>
152
153The filter should implement one or more of the following callbacks,
154which are registered via <A HREF="smfi_register.html">smfi_register</A>:
155
156<P>
157<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
158
159<TR><TD><A HREF="xxfi_connect.html">xxfi_connect</A></TD><TD>connection info</TD></TR>
160
161<TR><TD><A HREF="xxfi_helo.html">xxfi_helo</A></TD><TD>SMTP HELO/EHLO command</TD></TR>
162
163<TR><TD><A HREF="xxfi_envfrom.html">xxfi_envfrom</A></TD><TD>envelope sender</TD></TR>
164
165<TR><TD><A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A></TD><TD>envelope recipient</TD></TR>
166
167<TR><TD><A HREF="xxfi_data.html">xxfi_data</A></TD><TD>DATA command</TD></TR>
168
169<TR><TD><A HREF="xxfi_unknown.html">xxfi_unknown</A></TD><TD>Unknown SMTP command</TD></TR>
170
171<TR><TD><A HREF="xxfi_header.html">xxfi_header</A></TD><TD>header</TD></TR>
172
173<TR><TD><A HREF="xxfi_eoh.html">xxfi_eoh</A></TD><TD>end of header</TD></TR>
174
175<TR><TD><A HREF="xxfi_body.html">xxfi_body</A></TD><TD>body block</TD></TR>
176
177<TR><TD><A HREF="xxfi_eom.html">xxfi_eom</A></TD><TD>end of message</TD></TR>
178
179<TR><TD><A HREF="xxfi_abort.html">xxfi_abort</A></TD><TD>message aborted</TD></TR>
180
181<TR><TD><A HREF="xxfi_close.html">xxfi_close</A></TD><TD>connection cleanup</TD></TR>
182
183<TR><TD><A HREF="xxfi_negotiate.html">xxfi_negotiate</A></TD><TD>option negotiattion</TD></TR>
184
185</TABLE>
186
187<P>
188The above callbacks should all return one of the following return values,
189having the indicated meanings.  Any return other than one of the below
190values constitutes an error, and will cause sendmail to terminate its
191connection to the offending filter.
192
193<P><A NAME="conn-spec">Milter</A> distinguishes between recipient-,
194message-, and connection-oriented routines.  Recipient-oriented
195callbacks may affect the processing of a single message recipient;
196message-oriented callbacks, a single message; connection-oriented
197callbacks, an entire connection (during which multiple messages may be
198delivered to multiple sets of recipients).
199<A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A> is recipient-oriented.
200<A HREF="xxfi_connect.html">xxfi_connect</A>,
201<A HREF="xxfi_helo.html">xxfi_helo</A> and
202<A HREF="xxfi_close.html">xxfi_close</A> are connection-oriented.  All
203other callbacks are message-oriented.
204
205<P>
206<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2>
207  <TR BGCOLOR="#dddddd"><TH>Return value</TH><TH>Description</TH></TR>
208  <TR VALIGN="TOP">
209     <TD>SMFIS_CONTINUE</TD>
210     <TD>Continue processing the current connection, message, or recipient.
211     </TD>
212  </TR>
213  <TR VALIGN="TOP">
214     <TD>SMFIS_REJECT</TD>
215     <TD>For a connection-oriented routine, reject this connection; call <A HREF="xxfi_close.html">xxfi_close</A>.<BR>
216        For a message-oriented routine (except
217	<A HREF="xxfi_eom.html">xxfi_eom</A> or
218        <A HREF="xxfi_abort.html">xxfi_abort</A>), reject this message.<BR>
219	For a recipient-oriented routine, reject the current recipient (but continue processing the current message).
220     </TD>
221  </TR>
222  <TR valign="top">
223     <TD>SMFIS_DISCARD</TD>
224     <TD>For a message- or recipient-oriented routine, accept this message, but silently discard it.<BR>
225     SMFIS_DISCARD should not be returned by a connection-oriented routine.
226     </TD>
227  </TR>
228  <TR valign="top">
229     <TD>SMFIS_ACCEPT</TD>
230     <TD>For a connection-oriented routine, accept this connection without further filter processing; call <A HREF="xxfi_close.html">xxfi_close</A>.<BR>
231         For a message- or recipient-oriented routine, accept this message without further filtering.<BR>
232     </TD>
233  </TR>
234  <TR valign="top">
235     <TD>SMFIS_TEMPFAIL</TD>
236     <TD>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code.
237	 For a message-oriented routine (except <A HREF="xxfi_envfrom.html">xxfi_envfrom</A>), fail for this message. <BR>
238	 For a connection-oriented routine, fail for this connection; call <A HREF="xxfi_close.html">xxfi_close</A>. <BR>
239	 For a recipient-oriented routine, only fail for the current recipient; continue message processing.
240     </TD>
241  </TR>
242
243  <TR valign="top">
244     <TD><A NAME="SMFIS_SKIP">SMFIS_SKIP</A></TD>
245     <TD>Skip further callbacks of the same type in this transaction.
246	Currently this return value is only allowed in
247	<A HREF="xxfi_body.html">xxfi_body()</A>.
248	It can be used if a milter has received sufficiently many
249	body chunks to make a decision, but still wants to invoke
250 	message modification functions that are only allowed to be called from
251	<A HREF="xxfi_eom.html">xxfi_eom()</A>.
252	Note: the milter <EM>must</EM>
253	<A HREF="xxfi_negotiate.html">negotiate</A>
254	this behavior with the MTA, i.e., it must check whether
255	the protocol action
256	<A HREF="xxfi_negotiate.html#SMFIP_SKIP"><CODE>SMFIP_SKIP</CODE></A>
257	is available and if so, the milter must request it.
258     </TD>
259  </TR>
260
261  <TR valign="top">
262     <TD><A NAME="SMFIS_NOREPLY">SMFIS_NOREPLY</A></TD>
263     <TD>Do not send a reply back to the MTA.
264	The milter <EM>must</EM>
265	<A HREF="xxfi_negotiate.html">negotiate</A>
266	this behavior with the MTA, i.e., it must check whether
267	the appropriate protocol action
268	<A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
269	is available and if so, the milter must request it.
270	If you set the
271	<A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
272	protocol action for a callback, that callback <EM>must</EM>
273	always reply with
274	SMFIS_NOREPLY.
275	Using any other reply code is a violation of the API.
276	If in some cases your callback may return another value
277	(e.g., due to some resource shortages), then you
278	<EM>must not</EM> set
279	<A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
280	and you must use
281	SMFIS_CONTINUE as the default return code.
282	(Alternatively you can try to delay reporting the problem to
283	a later callback for which
284	<A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
285	is not set.)
286     </TD>
287  </TR>
288
289</TABLE>
290
291<H2><A NAME="Miscellaneous">Miscellaneous</A></H2>
292
293<P>
294<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
295
296<TR><TD><A HREF="smfi_version.html">smfi_version</A></TD><TD>libmilter (runtime) version info</TD></TR>
297
298<TR><TD><A HREF="smfi_setsymlist.html">smfi_setsymlist</A></TD><TD>
299Set the list of macros that the milter wants to receive from the MTA
300for a protocol stage.
301</TD></TR>
302
303</TABLE>
304
305<P>
306<TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Constant</TH><TH>Description</TH></TR>
307
308<TR><TD><A HREF="smfi_version.html">SMFI_VERSION</A></TD><TD>libmilter (compile time) version info</TD></TR>
309
310</TABLE>
311
312
313<HR SIZE="1">
314<FONT SIZE="-1">
315Copyright (c) 2000, 2003, 2006, 2009 Sendmail, Inc. and its suppliers.
316All rights reserved.
317<BR>
318By using this file, you agree to the terms and conditions set
319forth in the LICENSE.
320</FONT>
321</BODY>
322</HTML>
323