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