1168515Sgshapiro<HTML>
2168515Sgshapiro<HEAD><TITLE>smfi_register</TITLE></HEAD>
3168515Sgshapiro<BODY>
4132943Sgshapiro<!--
5266692Sgshapiro$Id: smfi_register.html,v 1.19 2013-11-22 20:51:39 ca Exp $
6132943Sgshapiro-->
7168515Sgshapiro<H1>smfi_register</H1>
890792Sgshapiro
9168515Sgshapiro<TABLE border="0" cellspacing=4 cellpadding=4>
1090792Sgshapiro<!---------- Synopsis ----------->
11168515Sgshapiro<TR><TH valign="top" align=left width=100>SYNOPSIS</TH><TD>
12168515Sgshapiro<PRE>
1390792Sgshapiro#include &lt;libmilter/mfapi.h&gt;
1490792Sgshapiroint smfi_register(
15120256Sgshapiro	smfiDesc descr
1690792Sgshapiro);
17168515Sgshapiro</PRE>
1890792SgshapiroRegister a set of filter callbacks.
19168515Sgshapiro</TD></TR>
2090792Sgshapiro
2190792Sgshapiro<!----------- Description ---------->
22168515Sgshapiro<TR><TH valign="top" align=left>DESCRIPTION</TH><TD>
23168515Sgshapiro<TABLE border="1" cellspacing=1 cellpadding=1>
24168515Sgshapiro<TR align="left" valign=top>
25168515Sgshapiro<TH width="80">Called When</TH>
26168515Sgshapiro<TD>smfi_register must be called before smfi_main</TD>
27168515Sgshapiro</TR>
28168515Sgshapiro<TR align="left" valign=top>
29168515Sgshapiro<TH width="80">Effects</TH>
30168515Sgshapiro<TD>smfi_register creates a filter using the information given in the
31168515SgshapirosmfiDesc argument.
32168515SgshapiroMultiple (successful) calls to smfi_register within a
33168515Sgshapirosingle process are not allowed,
34168515Sgshapiroi.e., only one filter can be successfully registered.
35168515SgshapiroNote, however, that the library may not check whether this restriction
36168515Sgshapirois obeyed.
37168515Sgshapiro</TD>
38168515Sgshapiro</TR>
39168515Sgshapiro</TABLE>
4090792Sgshapiro
4190792Sgshapiro<!----------- Arguments ---------->
42168515Sgshapiro<TR><TH valign="top" align=left>ARGUMENTS</TH><TD>
43168515Sgshapiro    <TABLE border="1" cellspacing=0>
44168515Sgshapiro    <TR bgcolor="#dddddd"><TH>Argument</TH><TH>Description</TH></TR>
45168515Sgshapiro    <TR valign="top"><TD>descr</TD>
46168515Sgshapiro	<TD>
47168515SgshapiroA filter descriptor of type smfiDesc describing the filter's functions.
48168515Sgshapiro<A NAME="smfiDesc">The structure</A> has the following members:
49168515Sgshapiro<PRE>
5090792Sgshapirostruct smfiDesc
5190792Sgshapiro{
5290792Sgshapiro	char		*xxfi_name;	/* filter name */
5390792Sgshapiro	int		xxfi_version;	/* version code -- do not change */
54168515Sgshapiro	unsigned long	xxfi_flags;	/* <A href="#flags">flags</A> */
5590792Sgshapiro
5690792Sgshapiro	/* connection info filter */
57168515Sgshapiro	sfsistat	(*<A href="xxfi_connect.html">xxfi_connect</A>)(SMFICTX *, char *, _SOCK_ADDR *);
5890792Sgshapiro	/* SMTP HELO command filter */
59168515Sgshapiro	sfsistat	(*<A href="xxfi_helo.html">xxfi_helo</A>)(SMFICTX *, char *);
6090792Sgshapiro	/* envelope sender filter */
61168515Sgshapiro	sfsistat	(*<A href="xxfi_envfrom.html">xxfi_envfrom</A>)(SMFICTX *, char **);
6290792Sgshapiro	/* envelope recipient filter */
63168515Sgshapiro	sfsistat	(*<A href="xxfi_envrcpt.html">xxfi_envrcpt</A>)(SMFICTX *, char **);
6490792Sgshapiro	/* header filter */
65168515Sgshapiro	sfsistat	(*<A href="xxfi_header.html">xxfi_header</A>)(SMFICTX *, char *, char *);
6690792Sgshapiro	/* end of header */
67168515Sgshapiro	sfsistat	(*<A href="xxfi_eoh.html">xxfi_eoh</A>)(SMFICTX *);
6890792Sgshapiro	/* body block */
69168515Sgshapiro	sfsistat	(*<A href="xxfi_body.html">xxfi_body</A>)(SMFICTX *, unsigned char *, size_t);
7090792Sgshapiro	/* end of message */
71168515Sgshapiro	sfsistat	(*<A href="xxfi_eom.html">xxfi_eom</A>)(SMFICTX *);
7290792Sgshapiro	/* message aborted */
73168515Sgshapiro	sfsistat	(*<A href="xxfi_abort.html">xxfi_abort</A>)(SMFICTX *);
7490792Sgshapiro	/* connection cleanup */
75168515Sgshapiro	sfsistat	(*<A href="xxfi_close.html">xxfi_close</A>)(SMFICTX *);
76168515Sgshapiro
77168515Sgshapiro	/* any unrecognized or unimplemented command filter */
78168515Sgshapiro	sfsistat	(*xxfi_unknown)(SMFICTX *, const char *);
79168515Sgshapiro
80168515Sgshapiro	/* SMTP DATA command filter */
81168515Sgshapiro	sfsistat	(*xxfi_data)(SMFICTX *);
82168515Sgshapiro
83168515Sgshapiro	/* negotiation callback */
84168515Sgshapiro	sfsistat (*<A HREF="xxfi_negotiate.html">xxfi_negotiate</A>)(SMFICTX *,
85168515Sgshapiro		unsigned long, unsigned long, unsigned long, unsigned long,
86168515Sgshapiro		unsigned long *, unsigned long *, unsigned long *, unsigned long *);
8790792Sgshapiro};
88168515Sgshapiro</PRE>
8990792Sgshapiro
90168515SgshapiroA NULL value for any callback function indicates that the filter
91168515Sgshapirodoes not wish to process the given type of information,
92168515Sgshapirosimply returning SMFIS_CONTINUE.
93168515Sgshapiro	</TD></TR>
94168515Sgshapiro    </TABLE>
95168515Sgshapiro</TD></TR>
9690792Sgshapiro
9790792Sgshapiro<!----------- Return values ---------->
98168515Sgshapiro<TR>
99168515Sgshapiro<TH valign="top" align=left>RETURN VALUES</TH> 
10090792Sgshapiro
101168515Sgshapiro<TD>
10290792Sgshapirosmfi_register may return MI_FAILURE for any of the following reasons:
103168515Sgshapiro<UL>
104168515Sgshapiro<LI>memory allocation failed.  
105168515Sgshapiro<LI>incompatible version or illegal flags value.
106168515Sgshapiro</UL>
10790792Sgshapiro
108168515Sgshapiro</TD>
109168515Sgshapiro</TR>
11090792Sgshapiro
11190792Sgshapiro<!----------- Notes ---------->
112168515Sgshapiro<TR align="left" valign=top>
113168515Sgshapiro<TH>NOTES</TH> 
114168515Sgshapiro<TD>
11590792Sgshapiro
116168515Sgshapiro<A NAME="flags">The xxfi_flags</A>
117168515Sgshapirofield should contain the bitwise OR of zero or more of
11890792Sgshapirothe following values, describing the actions the filter may take:
11990792Sgshapiro<TABLE BORDER CELLPADDING="1" cellspacing=1>
120168515Sgshapiro<TR valign="top" bgcolor="#dddddd"><TH align="left">Flag</TH><TH align="center">Description</TH></TR>
12190792Sgshapiro  <TR align="left" valign=top>
12290792Sgshapiro    <TD>
12390792Sgshapiro        SMFIF_ADDHDRS
12490792Sgshapiro    </TD>
12590792Sgshapiro    <TD>
126168515Sgshapiro        This filter may <A HREF="smfi_addheader.html">add headers</A>.
12790792Sgshapiro    </TD>
12890792Sgshapiro  </TR>
12990792Sgshapiro  <TR align="left" valign=top>
13090792Sgshapiro    <TD>
13190792Sgshapiro        SMFIF_CHGHDRS
13290792Sgshapiro    </TD>
13390792Sgshapiro    <TD>
134168515Sgshapiro        This filter may
135168515Sgshapiro	<A HREF="smfi_chgheader.html">change and/or delete headers</A>.
13690792Sgshapiro    </TD>
13790792Sgshapiro  </TR>
13890792Sgshapiro  <TR align="left" valign=top>
13990792Sgshapiro    <TD VALIGN="TOP">
14090792Sgshapiro        SMFIF_CHGBODY
14190792Sgshapiro    </TD>
14290792Sgshapiro    <TD>
143168515Sgshapiro        This filter may
144168515Sgshapiro	<A HREF="smfi_replacebody.html">replace the body</A> during filtering.
14590792Sgshapiro        This may have significant performance impact
14690792Sgshapiro        if other filters do body filtering after this filter.
14790792Sgshapiro    </TD>
14890792Sgshapiro  </TR>
14990792Sgshapiro  <TR>
15090792Sgshapiro    <TD VALIGN="TOP">
15190792Sgshapiro        SMFIF_ADDRCPT
15290792Sgshapiro    </TD>
15390792Sgshapiro    <TD>
154168515Sgshapiro        This filter may
155168515Sgshapiro	<A HREF="smfi_addrcpt.html">add recipients</A>
156168515Sgshapiro	to the message.
15790792Sgshapiro    </TD>
15890792Sgshapiro  </TR>
15990792Sgshapiro  <TR>
16090792Sgshapiro    <TD VALIGN="TOP">
161168515Sgshapiro	SMFIF_ADDRCPT_PAR
162168515Sgshapiro    </TD>
163168515Sgshapiro    <TD>
164168515Sgshapiro	This filter may
165168515Sgshapiro	<A HREF="smfi_addrcpt_par.html">add recipients including ESMTP args</A>.
166168515Sgshapiro    </TD>
167168515Sgshapiro  </TR>
168168515Sgshapiro  <TR>
169168515Sgshapiro    <TD VALIGN="TOP">
17090792Sgshapiro        SMFIF_DELRCPT
17190792Sgshapiro    </TD>
17290792Sgshapiro    <TD>
173168515Sgshapiro        This filter may
174168515Sgshapiro	<A HREF="smfi_delrcpt.html">remove recipients</A> from the message.
17590792Sgshapiro    </TD>
17690792Sgshapiro  </TR>
177168515Sgshapiro  <TR>
178168515Sgshapiro    <TD VALIGN="TOP">
179168515Sgshapiro	SMFIF_QUARANTINE
180168515Sgshapiro    </TD>
181168515Sgshapiro    <TD>
182168515Sgshapiro	This filter may
183168515Sgshapiro	<A HREF="smfi_quarantine.html">quarantine</A> a message.
184168515Sgshapiro    </TD>
185168515Sgshapiro  </TR>
186168515Sgshapiro
187168515Sgshapiro  <TR>
188168515Sgshapiro    <TD VALIGN="TOP">
189168515Sgshapiro	SMFIF_CHGFROM
190168515Sgshapiro    </TD>
191168515Sgshapiro    <TD>
192168515Sgshapiro	This filter may
193168515Sgshapiro	<A HREF="smfi_chgfrom.html">change the envelope sender</A> (MAIL).
194168515Sgshapiro    </TD>
195168515Sgshapiro  </TR>
196168515Sgshapiro
197168515Sgshapiro  <TR>
198168515Sgshapiro    <TD VALIGN="TOP">
199168515Sgshapiro	SMFIF_SETSYMLIST
200168515Sgshapiro    </TD>
201168515Sgshapiro    <TD>
202168515Sgshapiro	This filter can
203168515Sgshapiro	<A HREF="smfi_setsymlist.html">send a set of symbols (macros)</A>
204168515Sgshapiro	that it wants.
205168515Sgshapiro    </TD>
206168515Sgshapiro  </TR>
207168515Sgshapiro
20890792Sgshapiro</TABLE>
20990792Sgshapiro
210168515Sgshapiro</TD>
211168515Sgshapiro</TR>
21290792Sgshapiro
213168515Sgshapiro</TABLE>
21490792Sgshapiro
215168515Sgshapiro<HR size="1">
216168515Sgshapiro<FONT size="-1">
217261363SgshapiroCopyright (c) 2000-2001, 2003, 2006 Proofpoint, Inc. and its suppliers.
21890792SgshapiroAll rights reserved.
219168515Sgshapiro<BR>
22090792SgshapiroBy using this file, you agree to the terms and conditions set
221112810Sgshapiroforth in the LICENSE.
222168515Sgshapiro</FONT>
223168515Sgshapiro</BODY>
224168515Sgshapiro</HTML>
225