1168515Sgshapiro<HTML>
2168515Sgshapiro<HEAD><TITLE>smfi_addheader</TITLE></HEAD>
3168515Sgshapiro<BODY>
4132943Sgshapiro<!--
5203004Sgshapiro$Id: smfi_addheader.html,v 1.20 2009/05/18 23:51:23 ca Exp $
6132943Sgshapiro-->
7168515Sgshapiro<H1>smfi_addheader</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_addheader(
1590792Sgshapiro	SMFICTX *ctx,
1690792Sgshapiro	char *headerf,
1790792Sgshapiro	char *headerv
1890792Sgshapiro);
19168515Sgshapiro</PRE>
2090792SgshapiroAdd a header to the current message.
21168515Sgshapiro</TD></TR>
2290792Sgshapiro
2390792Sgshapiro<!----------- Description ---------->
24168515Sgshapiro<TR><TH valign="top" align=left>DESCRIPTION</TH><TD>
25168515Sgshapiro<TABLE border="1" cellspacing=1 cellpadding=4>
26168515Sgshapiro<TR align="left" valign=top>
27168515Sgshapiro<TH width="80">Called When</TH>
28168515Sgshapiro<TD>Called only from <A href="xxfi_eom.html">xxfi_eom</A>.</TD>
29168515Sgshapiro</TR>
30168515Sgshapiro<TR align="left" valign=top>
31168515Sgshapiro<TH width="80">Effects</TH>
32168515Sgshapiro<TD>Adds a header to the current message.</TD>
33168515Sgshapiro</TR>
34168515Sgshapiro</TABLE>
3590792Sgshapiro
3690792Sgshapiro<!----------- Arguments ---------->
37168515Sgshapiro<TR><TH valign="top" align=left>ARGUMENTS</TH><TD>
38168515Sgshapiro    <TABLE border="1" cellspacing=0>
39168515Sgshapiro    <TR bgcolor="#dddddd"><TH>Argument</TH><TH>Description</TH></TR>
40168515Sgshapiro    <TR valign="top"><TD>ctx</TD>
41168515Sgshapiro	<TD>Opaque context structure.
42168515Sgshapiro	</TD></TR>
43168515Sgshapiro    <TR valign="top"><TD>headerf</TD>
44168515Sgshapiro	<TD>The header name, a non-NULL, null-terminated string.
45168515Sgshapiro	</TD></TR>
46168515Sgshapiro    <TR valign="top"><TD>headerv</TD>
47168515Sgshapiro	<TD>The header value to be added, a non-NULL, null-terminated string.
48168515Sgshapiro	This may be the empty string.  
49168515Sgshapiro	</TD></TR>
50168515Sgshapiro    </TABLE>
51168515Sgshapiro</TD></TR>
5290792Sgshapiro
5390792Sgshapiro<!----------- Return values ---------->
54168515Sgshapiro<TR>
55168515Sgshapiro<TH valign="top" align=left>RETURN VALUES</TH> 
5690792Sgshapiro
57168515Sgshapiro<TD>smfi_addheader returns MI_FAILURE if:
58168515Sgshapiro<UL><LI>headerf or headerv is NULL.
59168515Sgshapiro    <LI>Adding headers in the current connection state is invalid.
60168515Sgshapiro    <LI>Memory allocation fails.
61168515Sgshapiro    <LI>A network error occurs.
62168515Sgshapiro    <LI>SMFIF_ADDHDRS was not set when <A href="smfi_register.html">smfi_register</A> was called.
63168515Sgshapiro</UL>
6490792SgshapiroOtherwise, it returns MI_SUCCESS.
65168515Sgshapiro</TD>
66168515Sgshapiro</TR>
6790792Sgshapiro
6890792Sgshapiro<!----------- Notes ---------->
69168515Sgshapiro<TR align="left" valign=top>
70168515Sgshapiro<TH>NOTES</TH> 
71168515Sgshapiro<TD>
72168515Sgshapiro<UL><LI>smfi_addheader does not change a message's existing headers.
73168515SgshapiroTo change a header's current value, use
74168515Sgshapiro<A HREF="smfi_chgheader.html">smfi_chgheader</A>.
75168515Sgshapiro    <LI>A filter which calls smfi_addheader must have set the SMFIF_ADDHDRS
76168515Sgshapiro	flag in the smfiDesc_str passed to
77168515Sgshapiro	<A href="smfi_register.html">smfi_register</A>.
78168515Sgshapiro    <LI>For smfi_addheader, filter order is important.
79168515Sgshapiro	<B>Later filters will see the header changes made by earlier ones.</B>
80168515Sgshapiro    <LI>Neither the name nor the value of the header is checked for
81168515Sgshapiro    standards compliance.
82168515Sgshapiro    However, each line of the header must be under 2048 characters
83168515Sgshapiro    and should be under 998 characters.
84168515Sgshapiro    If longer headers are needed, make them multi-line.
85168515Sgshapiro    To make a multi-line header,
86168515Sgshapiro    insert a line feed (ASCII 0x0a, or <TT>\n</TT> in C)
87168515Sgshapiro    followed by at least one whitespace character
88168515Sgshapiro    such as a space (ASCII 0x20) or tab (ASCII 0x09, or <TT>\t</TT> in C).
89168515Sgshapiro    The line feed should NOT be preceded by a carriage return (ASCII 0x0d);
90168515Sgshapiro    the MTA will add this automatically.
91168515Sgshapiro    <B>It is the filter writer's responsibility to ensure that no standards
92168515Sgshapiro    are violated.</B>
93203004Sgshapiro    <LI>The MTA adds a leading space to an added header value unless
94203004Sgshapiro    the flag
95203004Sgshapiro<A HREF="xxfi_negotiate.html#SMFIP_HDR_LEADSPC"><CODE>SMFIP_HDR_LEADSPC</CODE></A>
96203004Sgshapiro    is set, in which case the milter
97203004Sgshapiro    must include any desired leading spaces itself.
98168515Sgshapiro</UL>
99168515Sgshapiro</TD>
100168515Sgshapiro</TR>
10190792Sgshapiro
10298121Sgshapiro<!----------- Example code ---------->
103168515Sgshapiro<TR>
104168515Sgshapiro<TH valign="top" align=left>EXAMPLE</TH> 
10598121Sgshapiro
106168515Sgshapiro<TD>
107168515Sgshapiro <PRE>
10898121Sgshapiro  int ret;
10998121Sgshapiro  SMFICTX *ctx;
11098121Sgshapiro
11198121Sgshapiro  ...
11298121Sgshapiro
11398121Sgshapiro  ret = smfi_addheader(ctx, "Content-Type",
11498121Sgshapiro                       "multipart/mixed;\n\tboundary=\"foobar\"");
115168515Sgshapiro </PRE>
116168515Sgshapiro</TD>
117168515Sgshapiro</TR>
11898121Sgshapiro
119168515Sgshapiro</TABLE>
12090792Sgshapiro
121168515Sgshapiro<HR size="1">
122168515Sgshapiro<FONT size="-1">
123203004SgshapiroCopyright (c) 2000-2003, 2006, 2009 Sendmail, Inc. and its suppliers.
12490792SgshapiroAll rights reserved.
125168515Sgshapiro<BR>
12690792SgshapiroBy using this file, you agree to the terms and conditions set
127112810Sgshapiroforth in the LICENSE.
128168515Sgshapiro</FONT>
129168515Sgshapiro</BODY>
130168515Sgshapiro</HTML>
131