2 <HEAD><TITLE>smfi_register</TITLE></HEAD>
5 $Id: smfi_register.html,v 1.18 2006/12/20 18:37:11 ca Exp $
9 <TABLE border="0" cellspacing=4 cellpadding=4>
10 <!---------- Synopsis ----------->
11 <TR><TH valign="top" align=left width=100>SYNOPSIS</TH><TD>
13 #include <libmilter/mfapi.h>
18 Register a set of filter callbacks.
21 <!----------- Description ---------->
22 <TR><TH valign="top" align=left>DESCRIPTION</TH><TD>
23 <TABLE border="1" cellspacing=1 cellpadding=1>
24 <TR align="left" valign=top>
25 <TH width="80">Called When</TH>
26 <TD>smfi_register must be called before smfi_main</TD>
28 <TR align="left" valign=top>
29 <TH width="80">Effects</TH>
30 <TD>smfi_register creates a filter using the information given in the
32 Multiple (successful) calls to smfi_register within a
33 single process are not allowed,
34 i.e., only one filter can be successfully registered.
35 Note, however, that the library may not check whether this restriction
41 <!----------- Arguments ---------->
42 <TR><TH valign="top" align=left>ARGUMENTS</TH><TD>
43 <TABLE border="1" cellspacing=0>
44 <TR bgcolor="#dddddd"><TH>Argument</TH><TH>Description</TH></TR>
45 <TR valign="top"><TD>descr</TD>
47 A filter descriptor of type smfiDesc describing the filter's functions.
48 <A NAME="smfiDesc">The structure</A> has the following members:
52 char *xxfi_name; /* filter name */
53 int xxfi_version; /* version code -- do not change */
54 unsigned long xxfi_flags; /* <A href="#flags">flags</A> */
56 /* connection info filter */
57 sfsistat (*<A href="xxfi_connect.html">xxfi_connect</A>)(SMFICTX *, char *, _SOCK_ADDR *);
58 /* SMTP HELO command filter */
59 sfsistat (*<A href="xxfi_helo.html">xxfi_helo</A>)(SMFICTX *, char *);
60 /* envelope sender filter */
61 sfsistat (*<A href="xxfi_envfrom.html">xxfi_envfrom</A>)(SMFICTX *, char **);
62 /* envelope recipient filter */
63 sfsistat (*<A href="xxfi_envrcpt.html">xxfi_envrcpt</A>)(SMFICTX *, char **);
65 sfsistat (*<A href="xxfi_header.html">xxfi_header</A>)(SMFICTX *, char *, char *);
67 sfsistat (*<A href="xxfi_eoh.html">xxfi_eoh</A>)(SMFICTX *);
69 sfsistat (*<A href="xxfi_body.html">xxfi_body</A>)(SMFICTX *, unsigned char *, size_t);
71 sfsistat (*<A href="xxfi_eom.html">xxfi_eom</A>)(SMFICTX *);
73 sfsistat (*<A href="xxfi_abort.html">xxfi_abort</A>)(SMFICTX *);
74 /* connection cleanup */
75 sfsistat (*<A href="xxfi_close.html">xxfi_close</A>)(SMFICTX *);
77 /* any unrecognized or unimplemented command filter */
78 sfsistat (*xxfi_unknown)(SMFICTX *, const char *);
80 /* SMTP DATA command filter */
81 sfsistat (*xxfi_data)(SMFICTX *);
83 /* negotiation callback */
84 sfsistat (*<A HREF="xxfi_negotiate.html">xxfi_negotiate</A>)(SMFICTX *,
85 unsigned long, unsigned long, unsigned long, unsigned long,
86 unsigned long *, unsigned long *, unsigned long *, unsigned long *);
90 A NULL value for any callback function indicates that the filter
91 does not wish to process the given type of information,
92 simply returning SMFIS_CONTINUE.
97 <!----------- Return values ---------->
99 <TH valign="top" align=left>RETURN VALUES</TH>
102 smfi_register may return MI_FAILURE for any of the following reasons:
104 <LI>memory allocation failed.
105 <LI>incompatible version or illegal flags value.
111 <!----------- Notes ---------->
112 <TR align="left" valign=top>
116 <A NAME="flags">The xxfi_flags</A>
117 field should contain the bitwise OR of zero or more of
118 the following values, describing the actions the filter may take:
119 <TABLE BORDER CELLPADDING="1" cellspacing=1>
120 <TR valign="top" bgcolor="#dddddd"><TH align="left">Flag</TH><TH align="center">Description</TH></TR>
121 <TR align="left" valign=top>
126 This filter may <A HREF="smfi_addheader.html">add headers</A>.
129 <TR align="left" valign=top>
135 <A HREF="smfi_chgheader.html">change and/or delete headers</A>.
138 <TR align="left" valign=top>
144 <A HREF="smfi_replacebody.html">replace the body</A> during filtering.
145 This may have significant performance impact
146 if other filters do body filtering after this filter.
155 <A HREF="smfi_addrcpt.html">add recipients</A>
165 <A HREF="smfi_addrcpt_par.html">add recipients including ESMTP args</A>.
174 <A HREF="smfi_delrcpt.html">remove recipients</A> from the message.
183 <A HREF="smfi_quarantine.html">quarantine</A> a message.
193 <A HREF="smfi_chgfrom.html">change the envelope sender</A> (MAIL).
203 <A HREF="smfi_setsymlist.html">send a set of symbols (macros)</A>
217 Copyright (c) 2000-2001, 2003, 2006 Sendmail, Inc. and its suppliers.
220 By using this file, you agree to the terms and conditions set
221 forth in the LICENSE.