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