2 <HEAD><TITLE>smfi_register</TITLE></HEAD>
5 $Id: smfi_register.html,v 1.19 2013-11-22 20:51:39 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
42 <!----------- Arguments ---------->
43 <TR><TH valign="top" align=left>ARGUMENTS</TH><TD>
44 <TABLE border="1" cellspacing=0>
45 <TR bgcolor="#dddddd"><TH>Argument</TH><TH>Description</TH></TR>
46 <TR valign="top"><TD>descr</TD>
48 A filter descriptor of type smfiDesc describing the filter's functions.
49 <A NAME="smfiDesc">The structure</A> has the following members:
53 char *xxfi_name; /* filter name */
54 int xxfi_version; /* version code -- do not change */
55 unsigned long xxfi_flags; /* <A href="#flags">flags</A> */
57 /* connection info filter */
58 sfsistat (*<A href="xxfi_connect.html">xxfi_connect</A>)(SMFICTX *, char *, _SOCK_ADDR *);
59 /* SMTP HELO command filter */
60 sfsistat (*<A href="xxfi_helo.html">xxfi_helo</A>)(SMFICTX *, char *);
61 /* envelope sender filter */
62 sfsistat (*<A href="xxfi_envfrom.html">xxfi_envfrom</A>)(SMFICTX *, char **);
63 /* envelope recipient filter */
64 sfsistat (*<A href="xxfi_envrcpt.html">xxfi_envrcpt</A>)(SMFICTX *, char **);
66 sfsistat (*<A href="xxfi_header.html">xxfi_header</A>)(SMFICTX *, char *, char *);
68 sfsistat (*<A href="xxfi_eoh.html">xxfi_eoh</A>)(SMFICTX *);
70 sfsistat (*<A href="xxfi_body.html">xxfi_body</A>)(SMFICTX *, unsigned char *, size_t);
72 sfsistat (*<A href="xxfi_eom.html">xxfi_eom</A>)(SMFICTX *);
74 sfsistat (*<A href="xxfi_abort.html">xxfi_abort</A>)(SMFICTX *);
75 /* connection cleanup */
76 sfsistat (*<A href="xxfi_close.html">xxfi_close</A>)(SMFICTX *);
78 /* any unrecognized or unimplemented command filter */
79 sfsistat (*xxfi_unknown)(SMFICTX *, const char *);
81 /* SMTP DATA command filter */
82 sfsistat (*xxfi_data)(SMFICTX *);
84 /* negotiation callback */
85 sfsistat (*<A HREF="xxfi_negotiate.html">xxfi_negotiate</A>)(SMFICTX *,
86 unsigned long, unsigned long, unsigned long, unsigned long,
87 unsigned long *, unsigned long *, unsigned long *, unsigned long *);
91 A NULL value for any callback function indicates that the filter
92 does not wish to process the given type of information,
93 simply returning SMFIS_CONTINUE.
98 <!----------- Return values ---------->
100 <TH valign="top" align=left>RETURN VALUES</TH>
103 smfi_register may return MI_FAILURE for any of the following reasons:
105 <LI>memory allocation failed.
106 <LI>incompatible version or illegal flags value.
112 <!----------- Notes ---------->
113 <TR align="left" valign=top>
114 <TH><A NAME=Notes>NOTES</A></TH>
117 <A NAME="flags">The xxfi_flags</A>
118 field should contain the bitwise OR of zero or more of
119 the following values, describing the actions the filter may take:
120 <TABLE BORDER CELLPADDING="1" cellspacing=1>
121 <TR valign="top" bgcolor="#dddddd"><TH align="left">Flag</TH><TH align="center">Description</TH></TR>
122 <TR align="left" valign=top>
124 <A NAME="SMFIF_ADDHDRS">SMFIF_ADDHDRS</A>
127 This filter may <A HREF="smfi_addheader.html">add headers</A>.
130 <TR align="left" valign=top>
132 <A NAME="SMFIF_CHGHDRS">SMFIF_CHGHDRS</A>
136 <A HREF="smfi_chgheader.html">change and/or delete headers</A>.
139 <TR align="left" valign=top>
141 <A NAME="SMFIF_CHGBODY">SMFIF_CHGBODY</A>
145 <A HREF="smfi_replacebody.html">replace the body</A> during filtering.
146 This may have significant performance impact
147 if other filters do body filtering after this filter.
152 <A NAME="SMFIF_ADDRCPT">SMFIF_ADDRCPT</A>
156 <A HREF="smfi_addrcpt.html">add recipients</A>
162 <A NAME="SMFIF_ADDRCPT_PAR">SMFIF_ADDRCPT_PAR</A>
166 <A HREF="smfi_addrcpt_par.html">add recipients including ESMTP args</A>.
171 <A NAME="SMFIF_DELRCPT">SMFIF_DELRCPT</A>
175 <A HREF="smfi_delrcpt.html">remove recipients</A> from the message.
180 <A NAME="SMFIF_QUARANTINE">SMFIF_QUARANTINE</A>
184 <A HREF="smfi_quarantine.html">quarantine</A> a message.
190 <A NAME="SMFIF_CHGFROM">SMFIF_CHGFROM</A>
194 <A HREF="smfi_chgfrom.html">change the envelope sender</A> (MAIL).
200 <A NAME="SMFIF_SETSYMLIST">SMFIF_SETSYMLIST</A>
204 <A HREF="smfi_setsymlist.html">send a set of symbols (macros)</A>
218 Copyright (c) 2000-2001, 2003, 2006 Proofpoint, Inc. and its suppliers.
221 By using this file, you agree to the terms and conditions set
222 forth in the LICENSE.