1<HTML>
2<HEAD><TITLE>smfi_insheader</TITLE></HEAD>
3<BODY>
| 1<html>
2<head><title>smfi_insheader</title></head>
3<body>
|
4<!--
| 4<!--
|
5$Id: smfi_insheader.html,v 1.11 2013-11-22 20:51:39 ca Exp $
| 5$Id: smfi_insheader.html,v 1.3 2004/05/04 16:20:34 gshapiro Exp $
|
6-->
| 6-->
|
7<H1>smfi_insheader</H1>
| 7<h1>smfi_insheader</h1>
|
8
| 8
|
9<TABLE border="0" cellspacing=4 cellpadding=4>
| 9<table border="0" cellspacing=4 cellpadding=4>
|
10<!---------- Synopsis ----------->
| 10<!---------- Synopsis ----------->
|
11<TR><TH valign="top" align=left width=100>SYNOPSIS</TH><TD>
12<PRE>
| 11<tr><th valign="top" align=left width=150>SYNOPSIS</th><td>
12<pre>
|
13#include <libmilter/mfapi.h>
14int smfi_insheader(
15 SMFICTX *ctx,
16 int hdridx,
17 char *headerf,
18 char *headerv
19);
| 13#include <libmilter/mfapi.h>
14int smfi_insheader(
15 SMFICTX *ctx,
16 int hdridx,
17 char *headerf,
18 char *headerv
19);
|
20</PRE>
| 20</pre>
|
21Prepend a header to the current message.
| 21Prepend a header to the current message.
|
22</TD></TR>
| 22</td></tr>
|
23
24<!----------- Description ---------->
| 23
24<!----------- Description ---------->
|
25<TR><TH valign="top" align=left>DESCRIPTION</TH><TD>
26<TABLE border="1" cellspacing=1 cellpadding=4>
27<TR align="left" valign=top>
28<TH width="80">Called When</TH>
29<TD>Called only from <A href="xxfi_eom.html">xxfi_eom</A>.</TD>
30</TR>
31<TR align="left" valign=top>
32<TH width="80">Effects</TH>
33<TD>Prepends a header to the current message.</TD>
34</TR>
35</TABLE>
| 25<tr><th valign="top" align=left>DESCRIPTION</th><td>
26<table border="1" cellspacing=1 cellpadding=4>
27<tr align="left" valign=top>
28<th width="80">Called When</th>
29<td>Called only from <a href="xxfi_eom.html">xxfi_eom</a>.</td>
30</tr>
31<tr align="left" valign=top>
32<th width="80">Effects</th>
33<td>Prepends a header to the current message.</td>
34</tr>
35</table>
|
36
37<!----------- Arguments ---------->
| 36
37<!----------- Arguments ---------->
|
38<TR><TH valign="top" align=left>ARGUMENTS</TH><TD>
39 <TABLE border="1" cellspacing=0>
40 <TR bgcolor="#dddddd"><TH>Argument</TH><TH>Description</TH></TR>
41 <TR valign="top"><TD>ctx</TD>
42 <TD>Opaque context structure.
43 </TD></TR>
44 <TR valign="top"><TD>hdridx</TD>
45 <TD>The location in the internal header list where this header should
| 38<tr><th valign="top" align=left>ARGUMENTS</th><td>
39 <table border="1" cellspacing=0>
40 <tr bgcolor="#dddddd"><th>Argument</th><th>Description</th></tr>
41 <tr valign="top"><td>ctx</td>
42 <td>Opaque context structure.
43 </td></tr>
44 <tr valign="top"><td>hdridx</td>
45 <td>The location in the internal header list where this header should
|
46 be inserted; 0 makes it the topmost header, etc.
| 46 be inserted; 0 makes it the topmost header, etc.
|
47 </TD></TR>
48 <TR valign="top"><TD>headerf</TD>
49 <TD>The header name, a non-NULL, null-terminated string.
50 </TD></TR>
51 <TR valign="top"><TD>headerv</TD>
52 <TD>The header value to be added, a non-NULL, null-terminated string. This may be the empty string.
53 </TD></TR>
54 </TABLE>
55</TD></TR>
| 47 </td></tr>
48 <tr valign="top"><td>headerf</td>
49 <td>The header name, a non-NULL, null-terminated string.
50 </td></tr>
51 <tr valign="top"><td>headerv</td>
52 <td>The header value to be added, a non-NULL, null-terminated string. This may be the empty string.
53 </td></tr>
54 </table>
55</td></tr>
|
56
57<!----------- Return values ---------->
| 56
57<!----------- Return values ---------->
|
58<TR>
59<TH valign="top" align=left>RETURN VALUES</TH>
| 58<tr>
59<th valign="top" align=left>RETURN VALUES</th>
|
60
| 60
|
61<TD>smfi_insheader returns MI_FAILURE if:
62<UL><LI>headerf or headerv is NULL.
63 <LI>Adding headers in the current connection state is invalid.
64 <LI>Memory allocation fails.
65 <LI>A network error occurs.
66 <LI>SMFIF_ADDHDRS was not set when <A href="smfi_register.html">smfi_register</A> was called.
67</UL>
| 61<td>smfi_insheader returns MI_FAILURE if:
62<ul><li>headerf or headerv is NULL.
63 <li>Adding headers in the current connection state is invalid.
64 <li>Memory allocation fails.
65 <li>A network error occurs.
66 <li>SMFIF_ADDHDRS was not set when <a href="smfi_register.html">smfi_register</a> was called.
67</ul>
|
68Otherwise, it returns MI_SUCCESS.
| 68Otherwise, it returns MI_SUCCESS.
|
69</TD>
70</TR>
| 69</td>
70</tr>
|
71
72<!----------- Notes ---------->
| 71
72<!----------- Notes ---------->
|
73<TR align="left" valign=top>
74<TH>NOTES</TH>
75<TD>
76<UL>
77 <LI>smfi_insheader does not change a message's existing headers.
78 To change a header's current value, use
79 <A HREF="smfi_chgheader.html">smfi_chgheader</A>.
80 <LI>A filter which calls smfi_insheader must have set the SMFIF_ADDHDRS
81 flag in the smfiDesc_str passed to
82 <A href="smfi_register.html">smfi_register</A>.
83 <LI>For smfi_insheader, filter order is important.
84 <B>Later filters will see the header changes made by earlier ones.</B>
85 <LI>A filter will receive <EM>only</EM> headers that have been sent
86 by the SMTP client and those header modifications by earlier filters.
87 It will <EM>not</EM> receive the headers that are inserted by sendmail
88 itself.
89 This makes the header insertion position highly dependent on
90 the headers that exist in the incoming message
91 and those that are configured to be added by sendmail.
92 For example, sendmail will always add a
93 <CODE>Received:</CODE> header to the beginning of the headers.
94 Setting <CODE>hdridx</CODE> to 0 will actually insert the header
95 before this <CODE>Received:</CODE> header.
96 However, later filters can be easily confused as they receive
97 the added header, but not the <CODE>Received:</CODE> header,
98 thus making it hard to insert a header at a fixed position.
99 <LI>If hdridx is a number larger than the number of headers in the message,
100 the header will simply be appended.
101 <LI>Neither the name nor the value of the header is checked for
102 standards compliance.
103 However, each line of the header must be under 2048 characters
104 and should be under 998 characters.
105 If longer headers are needed, make them multi-line.
106 To make a multi-line header,
107 insert a line feed (ASCII 0x0a, or <TT>\n</TT> in C)
108 followed by at least one whitespace character
109 such as a space (ASCII 0x20) or tab (ASCII 0x09, or <TT>\t</TT> in C).
110 The line feed should NOT be preceded by a carriage return (ASCII 0x0d);
111 the MTA will add this automatically.
112 <B>It is the filter writer's responsibility to ensure that no standards
113 are violated.</B>
114 <LI>The MTA adds a leading space to an inserted header value unless
115 the flag
116<A HREF="xxfi_negotiate.html#SMFIP_HDR_LEADSPC"><CODE>SMFIP_HDR_LEADSPC</CODE></A>
117 is set, in which case the milter
118 must include any desired leading spaces itself.
119</UL>
120</TD>
121</TR>
| 73<tr align="left" valign=top>
74<th>NOTES</th>
75<td>
76<ul><li>smfi_insheader does not change a message's existing headers.
77To change a header's current value, use <a
78href="smfi_chgheader.html">smfi_chgheader</a>.
79 <li>A filter which calls smfi_insheader must have set the SMFIF_ADDHDRS flag in the smfiDesc_str passed to <a href="smfi_register.html">smfi_register</a>.
80 <li>For smfi_insheader, filter order is important. <b>Later filters will see the header changes made by earlier ones.</b>
81 <li>If hdridx is a number larger than the number of headers in the message, the header will simply be appended.
82 <li>Neither the name nor the value of the header is checked for
83 standards compliance. However, each line of the header must be under
84 2048 characters and should be under 998 characters. If longer headers
85 are needed, make them multi-line. To make a multi-line header, insert
86 a line feed (ASCII 0x0a, or <tt>\n</tt> in C) followed by at least
87 one whitespace character such as a space (ASCII 0x20) or tab (ASCII 0x09,
88 or <tt>\t</tt> in C). The line feed should NOT be preceded by a
89 carriage return (ASCII 0x0d); the MTA will add this automatically.
90 <b>It is the filter writer's responsibility to ensure that no standards
91 are violated.</b>
92</ul>
93</td>
94</tr>
|
122
123<!----------- Example code ---------->
| 95
96<!----------- Example code ---------->
|
124<TR>
125<TH valign="top" align=left>EXAMPLE</TH>
| 97<tr>
98<th valign="top" align=left>EXAMPLE</th>
|
126
| 99
|
127<TD>
128 <PRE>
| 100<td>
101 <pre>
|
129 int ret;
130 SMFICTX *ctx;
131
132 ...
133
134 ret = smfi_insheader(ctx, 0, "First", "See me?");
| 102 int ret;
103 SMFICTX *ctx;
104
105 ...
106
107 ret = smfi_insheader(ctx, 0, "First", "See me?");
|
135 </PRE>
136</TD>
137</TR>
| 108 </pre>
109</td>
110</tr>
|
138
| 111
|
139</TABLE>
| 112</table>
|
140
| 113
|
141<HR size="1">
142<FONT size="-1">
143Copyright (c) 2004, 2006, 2009 Proofpoint, Inc. and its suppliers.
| 114<hr size="1">
115<font size="-1">
116Copyright (c) 2004 Sendmail, Inc. and its suppliers.
|
144All rights reserved.
| 117All rights reserved.
|
145<BR>
| 118<br>
|
146By using this file, you agree to the terms and conditions set
147forth in the LICENSE.
| 119By using this file, you agree to the terms and conditions set
120forth in the LICENSE.
|
148</FONT>
149</BODY>
150</HTML>
| 121</font>
122</body>
123</html>
|
| |