2 <HEAD><TITLE>Milter API</TITLE></HEAD>
5 $Id: api.html,v 1.38 2012/03/29 03:18:37 ca Exp $
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>
18 <H2><A NAME="LibraryControlFunctions">Library Control Functions</A></H2>
20 Before handing control to libmilter (by calling
21 <A HREF="smfi_main.html">smfi_main</A>), a filter may call the following
22 functions to set libmilter parameters.
23 In particular, the filter must call
24 <A HREF="smfi_register.html">smfi_register</A> to register its callbacks.
25 Each function will return either MI_SUCCESS or MI_FAILURE to
26 indicate the status of the operation.
29 None of these functions communicate with the MTA. All alter the
30 library's state, some of which is communicated to the MTA inside
31 <A HREF="smfi_main.html">smfi_main</A>.
34 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
36 <TR><TD><A HREF="smfi_opensocket.html">smfi_opensocket</A></TD><TD>Try to create the interface socket.</TD></TR>
38 <TR><TD><A HREF="smfi_register.html">smfi_register</A></TD><TD>Register a filter.</TD></TR>
40 <TR><TD><A HREF="smfi_setconn.html">smfi_setconn</A></TD><TD>Specify socket to use.</TD></TR>
42 <TR><TD><A HREF="smfi_settimeout.html">smfi_settimeout</A></TD><TD>Set timeout.</TD></TR>
44 <TR><TD><A HREF="smfi_setbacklog.html">smfi_setbacklog</A></TD><TD>Define the incoming <CODE>listen(2)</CODE> queue size.</TD></TR>
46 <TR><TD><A HREF="smfi_setdbg.html">smfi_setdbg</A></TD><TD>Set the milter library debugging (tracing) level.</TD></TR>
48 <TR><TD><A HREF="smfi_stop.html">smfi_stop</A></TD><TD>Cause an orderly shutdown.</TD></TR>
50 <TR><TD><A HREF="smfi_main.html">smfi_main</A></TD><TD>Hand control to libmilter.</TD></TR>
54 <H2><A NAME="DataAccessFunctions">Data Access Functions</A></H2>
56 The following functions may be called from within the filter-defined callbacks
57 to access information about the current connection or message.
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
61 of a symbol.</TD></TR>
63 <TR><TD><A HREF="smfi_getpriv.html">smfi_getpriv</A></TD><TD>Get the private data
66 <TR><TD><A HREF="smfi_setpriv.html">smfi_setpriv</A></TD><TD>Set the private data
69 <TR><TD><A HREF="smfi_setreply.html">smfi_setreply</A></TD><TD>Set the specific
70 reply code to be used.</TD></TR>
72 <TR><TD><A HREF="smfi_setmlreply.html">smfi_setmlreply</A></TD><TD>Set the
73 specific multi-line reply to be used.</TD></TR>
77 <H2><A NAME="MessageModificationFunctions">Message Modification Functions</A></H2>
79 The 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>.
81 All of these functions may invoke additional communication with the MTA.
82 They will return either MI_SUCCESS or MI_FAILURE to indicate the status of
83 the operation. Message data (senders, recipients, headers, body chunks)
84 passed to these functions via parameters is copied and does not need to be
85 preserved (i.e., allocated memory can be freed).
88 A filter must have set the appropriate flag (listed below) in the
89 description passed to <A HREF="smfi_register.html">smfi_register</A>
90 to call any message modification function. Failure to do so will
91 cause the MTA to treat a call to the function as a failure of the
92 filter, terminating its connection.
95 Note that the status returned indicates only whether or not the
96 filter's message was successfully sent to the MTA, not whether or not
97 the MTA performed the requested operation. For example,
98 <A HREF="smfi_addheader.html">smfi_addheader</A>, when called with an
99 illegal header name, will return MI_SUCCESS even though the MTA may
100 later refuse to add the illegal header.
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
104 the message.</TD><TD>SMFIF_ADDHDRS</TD></TR>
106 <TR><TD><A HREF="smfi_chgheader.html">smfi_chgheader</A></TD><TD>Change or delete a header.</TD><TD>SMFIF_CHGHDRS</TD></TR>
108 <TR><TD><A HREF="smfi_insheader.html">smfi_insheader</A></TD><TD>Insert a
109 header into the message.</TD><TD>SMFIF_ADDHDRS</TD></TR>
111 <TR><TD><A HREF="smfi_chgfrom.html">smfi_chgfrom</A></TD><TD>Change the
112 envelope sender address.</TD><TD>SMFIF_CHGFROM</TD></TR>
114 <TR><TD><A HREF="smfi_addrcpt.html">smfi_addrcpt</A></TD><TD>Add a recipient to
115 the envelope.</TD><TD>SMFIF_ADDRCPT</TD></TR>
117 <TR><TD><A HREF="smfi_addrcpt_par.html">smfi_addrcpt_par</A></TD><TD>Add
118 a recipient including ESMTP parameter to the envelope.
119 </TD><TD>SMFIF_ADDRCPT_PAR</TD></TR>
121 <TR><TD><A HREF="smfi_delrcpt.html">smfi_delrcpt</A></TD><TD>Delete a recipient
122 from the envelope.</TD><TD>SMFIF_DELRCPT</TD></TR>
124 <TR><TD><A HREF="smfi_replacebody.html">smfi_replacebody</A></TD><TD>Replace the
125 body of the message.</TD><TD>SMFIF_CHGBODY</TD></TR>
129 <H2>Other Message Handling Functions</H2>
131 The following functions provide special case handling instructions for
132 milter 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>.
134 All of these functions may invoke additional communication with the MTA.
135 They will return either MI_SUCCESS or MI_FAILURE to indicate the status of
139 Note that the status returned indicates only whether or not the
140 filter's message was successfully sent to the MTA, not whether or not
141 the MTA performed the requested operation.
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>
147 <TR><TD><A HREF="smfi_quarantine.html">smfi_quarantine</A></TD><TD>Quarantine a message.</TD></TR>
151 <H2><A NAME="Callbacks">Callbacks</A></H2>
153 The filter should implement one or more of the following callbacks,
154 which are registered via <A HREF="smfi_register.html">smfi_register</A>:
157 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
159 <TR><TD><A HREF="xxfi_connect.html">xxfi_connect</A></TD><TD>connection info</TD></TR>
161 <TR><TD><A HREF="xxfi_helo.html">xxfi_helo</A></TD><TD>SMTP HELO/EHLO command</TD></TR>
163 <TR><TD><A HREF="xxfi_envfrom.html">xxfi_envfrom</A></TD><TD>envelope sender</TD></TR>
165 <TR><TD><A HREF="xxfi_envrcpt.html">xxfi_envrcpt</A></TD><TD>envelope recipient</TD></TR>
167 <TR><TD><A HREF="xxfi_data.html">xxfi_data</A></TD><TD>DATA command</TD></TR>
169 <TR><TD><A HREF="xxfi_unknown.html">xxfi_unknown</A></TD><TD>Unknown SMTP command</TD></TR>
171 <TR><TD><A HREF="xxfi_header.html">xxfi_header</A></TD><TD>header</TD></TR>
173 <TR><TD><A HREF="xxfi_eoh.html">xxfi_eoh</A></TD><TD>end of header</TD></TR>
175 <TR><TD><A HREF="xxfi_body.html">xxfi_body</A></TD><TD>body block</TD></TR>
177 <TR><TD><A HREF="xxfi_eom.html">xxfi_eom</A></TD><TD>end of message</TD></TR>
179 <TR><TD><A HREF="xxfi_abort.html">xxfi_abort</A></TD><TD>message aborted</TD></TR>
181 <TR><TD><A HREF="xxfi_close.html">xxfi_close</A></TD><TD>connection cleanup</TD></TR>
183 <TR><TD><A HREF="xxfi_negotiate.html">xxfi_negotiate</A></TD><TD>option negotiattion</TD></TR>
188 The above callbacks should all return one of the following return values,
189 having the indicated meanings. Any return other than one of the below
190 values constitutes an error, and will cause sendmail to terminate its
191 connection to the offending filter.
193 <P><A NAME="conn-spec">Milter</A> distinguishes between recipient-,
194 message-, and connection-oriented routines. Recipient-oriented
195 callbacks may affect the processing of a single message recipient;
196 message-oriented callbacks, a single message; connection-oriented
197 callbacks, an entire connection (during which multiple messages may be
198 delivered 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
203 other callbacks are message-oriented.
206 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2>
207 <TR BGCOLOR="#dddddd"><TH>Return value</TH><TH>Description</TH></TR>
209 <TD>SMFIS_CONTINUE</TD>
210 <TD>Continue processing the current connection, message, or recipient.
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_abort.html">xxfi_abort</A>), reject this message.<BR>
218 For a recipient-oriented routine, reject the current recipient (but continue processing the current message).
222 <TD>SMFIS_DISCARD</TD>
223 <TD>For a message- or recipient-oriented routine, accept this message, but silently discard it.<BR>
224 SMFIS_DISCARD should not be returned by a connection-oriented routine.
228 <TD>SMFIS_ACCEPT</TD>
229 <TD>For a connection-oriented routine, accept this connection without further filter processing; call <A HREF="xxfi_close.html">xxfi_close</A>.<BR>
230 For a message- or recipient-oriented routine, accept this message without further filtering.<BR>
234 <TD>SMFIS_TEMPFAIL</TD>
235 <TD>Return a temporary failure, i.e., the corresponding SMTP command will return an appropriate 4xx status code.
236 For a message-oriented routine (except <A HREF="xxfi_envfrom.html">xxfi_envfrom</A>), fail for this message. <BR>
237 For a connection-oriented routine, fail for this connection; call <A HREF="xxfi_close.html">xxfi_close</A>. <BR>
238 For a recipient-oriented routine, only fail for the current recipient; continue message processing.
243 <TD><A NAME="SMFIS_SKIP">SMFIS_SKIP</A></TD>
244 <TD>Skip further callbacks of the same type in this transaction.
245 Currently this return value is only allowed in
246 <A HREF="xxfi_body.html">xxfi_body()</A>.
247 It can be used if a milter has received sufficiently many
248 body chunks to make a decision, but still wants to invoke
249 message modification functions that are only allowed to be called from
250 <A HREF="xxfi_eom.html">xxfi_eom()</A>.
251 Note: the milter <EM>must</EM>
252 <A HREF="xxfi_negotiate.html">negotiate</A>
253 this behavior with the MTA, i.e., it must check whether
255 <A HREF="xxfi_negotiate.html#SMFIP_SKIP"><CODE>SMFIP_SKIP</CODE></A>
256 is available and if so, the milter must request it.
261 <TD><A NAME="SMFIS_NOREPLY">SMFIS_NOREPLY</A></TD>
262 <TD>Do not send a reply back to the MTA.
263 The milter <EM>must</EM>
264 <A HREF="xxfi_negotiate.html">negotiate</A>
265 this behavior with the MTA, i.e., it must check whether
266 the appropriate protocol action
267 <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
268 is available and if so, the milter must request it.
270 <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
271 protocol action for a callback, that callback <EM>must</EM>
274 Using any other reply code is a violation of the API.
275 If in some cases your callback may return another value
276 (e.g., due to some resource shortages), then you
277 <EM>must not</EM> set
278 <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
280 SMFIS_CONTINUE as the default return code.
281 (Alternatively you can try to delay reporting the problem to
282 a later callback for which
283 <A HREF="xxfi_negotiate.html#SMFIP_NR_"><CODE>SMFIP_NR_*</CODE></A>
290 <H2><A NAME="Miscellaneous">Miscellaneous</A></H2>
293 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Function</TH><TH>Description</TH></TR>
295 <TR><TD><A HREF="smfi_version.html">smfi_version</A></TD><TD>libmilter (runtime) version info</TD></TR>
297 <TR><TD><A HREF="smfi_setsymlist.html">smfi_setsymlist</A></TD><TD>
298 Set the list of macros that the milter wants to receive from the MTA
299 for a protocol stage.
305 <TABLE BORDER="1" CELLSPACING=0 CELLPADDING=2><TR BGCOLOR="#dddddd"><TH>Constant</TH><TH>Description</TH></TR>
307 <TR><TD><A HREF="smfi_version.html">SMFI_VERSION</A></TD><TD>libmilter (compile time) version info</TD></TR>
314 Copyright (c) 2000, 2003, 2006, 2009 Sendmail, Inc. and its suppliers.
317 By using this file, you agree to the terms and conditions set
318 forth in the LICENSE.