smfi_register.html revision 363466 
1<HTML>
2<HEAD><TITLE>smfi_register</TITLE></HEAD>
3<BODY>
4<!--
5$Id: smfi_register.html,v 1.19 2013-11-22 20:51:39 ca Exp $
6-->
7<H1>smfi_register</H1>
8
9<TABLE border="0" cellspacing=4 cellpadding=4>
10<!---------- Synopsis ----------->
11<TR><TH valign="top" align=left width=100>SYNOPSIS</TH><TD>
12<PRE>
13#include &lt;libmilter/mfapi.h&gt;
14int smfi_register(
15	smfiDesc descr
16);
17</PRE>
18Register a set of filter callbacks.
19</TD></TR>
20
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>
27</TR>
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
31smfiDesc argument.
32Multiple (successful) calls to smfi_register within a
33single process are not allowed,
34i.e., only one filter can be successfully registered.
35Note, however, that the library may not check whether this restriction
36is obeyed.
37</TD>
38</TR>
39</TABLE>
40</TD></TR>
41
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>
47	<TD>
48A filter descriptor of type smfiDesc describing the filter's functions.
49<A NAME="smfiDesc">The structure</A> has the following members:
50<PRE>
51struct smfiDesc
52{
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> */
56
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 **);
65	/* header filter */
66	sfsistat	(*<A href="xxfi_header.html">xxfi_header</A>)(SMFICTX *, char *, char *);
67	/* end of header */
68	sfsistat	(*<A href="xxfi_eoh.html">xxfi_eoh</A>)(SMFICTX *);
69	/* body block */
70	sfsistat	(*<A href="xxfi_body.html">xxfi_body</A>)(SMFICTX *, unsigned char *, size_t);
71	/* end of message */
72	sfsistat	(*<A href="xxfi_eom.html">xxfi_eom</A>)(SMFICTX *);
73	/* message aborted */
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 *);
77
78	/* any unrecognized or unimplemented command filter */
79	sfsistat	(*xxfi_unknown)(SMFICTX *, const char *);
80
81	/* SMTP DATA command filter */
82	sfsistat	(*xxfi_data)(SMFICTX *);
83
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 *);
88};
89</PRE>
90
91A NULL value for any callback function indicates that the filter
92does not wish to process the given type of information,
93simply returning SMFIS_CONTINUE.
94	</TD></TR>
95    </TABLE>
96</TD></TR>
97
98<!----------- Return values ---------->
99<TR>
100<TH valign="top" align=left>RETURN VALUES</TH>
101
102<TD>
103smfi_register may return MI_FAILURE for any of the following reasons:
104<UL>
105<LI>memory allocation failed.
106<LI>incompatible version or illegal flags value.
107</UL>
108
109</TD>
110</TR>
111
112<!----------- Notes ---------->
113<TR align="left" valign=top>
114<TH><A NAME=Notes>NOTES</A></TH>
115<TD>
116
117<A NAME="flags">The xxfi_flags</A>
118field should contain the bitwise OR of zero or more of
119the 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>
123    <TD>
124        <A NAME="SMFIF_ADDHDRS">SMFIF_ADDHDRS</A>
125    </TD>
126    <TD>
127        This filter may <A HREF="smfi_addheader.html">add headers</A>.
128    </TD>
129  </TR>
130  <TR align="left" valign=top>
131    <TD>
132        <A NAME="SMFIF_CHGHDRS">SMFIF_CHGHDRS</A>
133    </TD>
134    <TD>
135        This filter may
136	<A HREF="smfi_chgheader.html">change and/or delete headers</A>.
137    </TD>
138  </TR>
139  <TR align="left" valign=top>
140    <TD VALIGN="TOP">
141        <A NAME="SMFIF_CHGBODY">SMFIF_CHGBODY</A>
142    </TD>
143    <TD>
144        This filter may
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.
148    </TD>
149  </TR>
150  <TR>
151    <TD VALIGN="TOP">
152        <A NAME="SMFIF_ADDRCPT">SMFIF_ADDRCPT</A>
153    </TD>
154    <TD>
155        This filter may
156	<A HREF="smfi_addrcpt.html">add recipients</A>
157	to the message.
158    </TD>
159  </TR>
160  <TR>
161    <TD VALIGN="TOP">
162	<A NAME="SMFIF_ADDRCPT_PAR">SMFIF_ADDRCPT_PAR</A>
163    </TD>
164    <TD>
165	This filter may
166	<A HREF="smfi_addrcpt_par.html">add recipients including ESMTP args</A>.
167    </TD>
168  </TR>
169  <TR>
170    <TD VALIGN="TOP">
171        <A NAME="SMFIF_DELRCPT">SMFIF_DELRCPT</A>
172    </TD>
173    <TD>
174        This filter may
175	<A HREF="smfi_delrcpt.html">remove recipients</A> from the message.
176    </TD>
177  </TR>
178  <TR>
179    <TD VALIGN="TOP">
180	<A NAME="SMFIF_QUARANTINE">SMFIF_QUARANTINE</A>
181    </TD>
182    <TD>
183	This filter may
184	<A HREF="smfi_quarantine.html">quarantine</A> a message.
185    </TD>
186  </TR>
187
188  <TR>
189    <TD VALIGN="TOP">
190	<A NAME="SMFIF_CHGFROM">SMFIF_CHGFROM</A>
191    </TD>
192    <TD>
193	This filter may
194	<A HREF="smfi_chgfrom.html">change the envelope sender</A> (MAIL).
195    </TD>
196  </TR>
197
198  <TR>
199    <TD VALIGN="TOP">
200	<A NAME="SMFIF_SETSYMLIST">SMFIF_SETSYMLIST</A>
201    </TD>
202    <TD>
203	This filter can
204	<A HREF="smfi_setsymlist.html">send a set of symbols (macros)</A>
205	that it wants.
206    </TD>
207  </TR>
208
209</TABLE>
210
211</TD>
212</TR>
213
214</TABLE>
215
216<HR size="1">
217<FONT size="-1">
218Copyright (c) 2000-2001, 2003, 2006 Proofpoint, Inc. and its suppliers.
219All rights reserved.
220<BR>
221By using this file, you agree to the terms and conditions set
222forth in the LICENSE.
223</FONT>
224</BODY>
225</HTML>
226