smfi_chgheader.html revision 363466
1<HTML> 2<HEAD><TITLE>smfi_chgheader</TITLE></HEAD> 3<BODY> 4<!-- 5$Id: smfi_chgheader.html,v 1.19 2013-11-22 20:51:39 ca Exp $ 6--> 7<H1>smfi_chgheader</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_chgheader( 15 SMFICTX *ctx, 16 char *headerf, 17 mi_int32 hdridx, 18 char *headerv 19); 20</PRE> 21Change or delete a message header. 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>Changes a header's value for 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>headerf</TD> 46 <TD>The header name, a non-NULL, null-terminated string. 47 </TD></TR> 48 <TR valign="top"><TD>hdridx</TD> 49 <TD>Header index value (1-based). A hdridx value of 1 will modify the first occurrence of a header named headerf. If hdridx is greater than the number of times headerf appears, a new copy of headerf will be added. 50 </TD></TR> 51 <TR valign="top"><TD>headerv</TD> 52 <TD>The new value of the given header. headerv == NULL implies that the header should be deleted. 53 </TD></TR> 54 </TABLE> 55</TD></TR> 56 57<!----------- Return values ----------> 58<TR> 59<TH valign="top" align=left>RETURN VALUES</TH> 60 61<TD> 62smfi_chgheader will return MI_FAILURE if 63<UL><LI>headerf is NULL 64 <LI>Modifying 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_CHGHDRS">SMFIF_CHGHDRS</A> is not set. 68</UL> 69Otherwise, it returns MI_SUCCESS. 70</TD></TR> 71 72<!----------- Notes ----------> 73<TR align="left" valign=top> 74<TH>NOTES</TH> 75<TD> 76<UL><LI>While smfi_chgheader may be used to add new headers, it is more efficient and far safer to use <A href="smfi_addheader.html">smfi_addheader</A>. 77 <LI>A filter which calls smfi_chgheader must have set the 78 <A HREF="smfi_register.html#SMFIF_CHGHDRS">SMFIF_CHGHDRS</A> flag. 79 <LI>For smfi_chgheader, filter order is important. <B>Later filters will see the header changes made by earlier ones.</B> 80 <LI>Neither the name nor the value of the header is checked for 81 standards compliance. However, each line of the header must be under 82 2048 characters and should be under 998 characters. If longer headers 83 are needed, make them multi-line. To make a multi-line header, insert 84 a line feed (ASCII 0x0a, or <TT>\n</TT> in C) followed by at least 85 one whitespace character such as a space (ASCII 0x20) or tab (ASCII 0x09, 86 or <TT>\t</TT> in C). The line feed should NOT be preceded by a 87 carriage return (ASCII 0x0d); the MTA will add this automatically. 88 <B>It is the filter writer's responsibility to ensure that no standards 89 are violated.</B> 90 <LI>The MTA adds a leading space to a header value unless 91 the flag 92<A HREF="xxfi_negotiate.html#SMFIP_HDR_LEADSPC"><CODE>SMFIP_HDR_LEADSPC</CODE></A> 93 is set, in which case the milter 94 must include any desired leading spaces itself. 95</UL> 96</TD> 97</TR> 98 99<!----------- Example code ----------> 100<TR> 101<TH valign="top" align=left>EXAMPLE</TH> 102 103<TD> 104 <PRE> 105 int ret; 106 SMFICTX *ctx; 107 108 ... 109 110 ret = smfi_chgheader(ctx, "Content-Type", 1, 111 "multipart/mixed;\n\tboundary=\"foobar\""); 112 </PRE> 113</TD> 114</TR> 115 116</TABLE> 117 118<HR size="1"> 119<FONT size="-1"> 120Copyright (c) 2000-2003, 2009 Proofpoint, Inc. and its suppliers. 121All rights reserved. 122<BR> 123By using this file, you agree to the terms and conditions set 124forth in the LICENSE. 125</FONT> 126</BODY> 127</HTML> 128