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