1168515Sgshapiro<HTML> 2168515Sgshapiro<HEAD><TITLE>smfi_chgheader</TITLE></HEAD> 3168515Sgshapiro<BODY> 4132943Sgshapiro<!-- 5266692Sgshapiro$Id: smfi_chgheader.html,v 1.19 2013-11-22 20:51:39 ca Exp $ 6132943Sgshapiro--> 7168515Sgshapiro<H1>smfi_chgheader</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 <libmilter/mfapi.h> 1490792Sgshapiroint smfi_chgheader( 1590792Sgshapiro SMFICTX *ctx, 1690792Sgshapiro char *headerf, 1790792Sgshapiro mi_int32 hdridx, 1890792Sgshapiro char *headerv 1990792Sgshapiro); 20168515Sgshapiro</PRE> 2190792SgshapiroChange or delete a message header. 22168515Sgshapiro</TD></TR> 2390792Sgshapiro 2490792Sgshapiro<!----------- Description ----------> 25168515Sgshapiro<TR><TH valign="top" align=left>DESCRIPTION</TH><TD> 26168515Sgshapiro<TABLE border="1" cellspacing=1 cellpadding=4> 27168515Sgshapiro<TR align="left" valign=top> 28168515Sgshapiro<TH width="80">Called When</TH> 29168515Sgshapiro<TD>Called only from <A href="xxfi_eom.html">xxfi_eom</A>.</TD> 30168515Sgshapiro</TR> 31168515Sgshapiro<TR align="left" valign=top> 32168515Sgshapiro<TH width="80">Effects</TH> 33168515Sgshapiro<TD>Changes a header's value for the current message.</TD> 34168515Sgshapiro</TR> 35168515Sgshapiro</TABLE> 3690792Sgshapiro 3790792Sgshapiro<!----------- Arguments ----------> 38168515Sgshapiro<TR><TH valign="top" align=left>ARGUMENTS</TH><TD> 39168515Sgshapiro <TABLE border="1" cellspacing=0> 40168515Sgshapiro <TR bgcolor="#dddddd"><TH>Argument</TH><TH>Description</TH></TR> 41168515Sgshapiro <TR valign="top"><TD>ctx</TD> 42168515Sgshapiro <TD>Opaque context structure. 43168515Sgshapiro </TD></TR> 44168515Sgshapiro <TR valign="top"><TD>headerf</TD> 45168515Sgshapiro <TD>The header name, a non-NULL, null-terminated string. 46168515Sgshapiro </TD></TR> 47168515Sgshapiro <TR valign="top"><TD>hdridx</TD> 48168515Sgshapiro <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. 49168515Sgshapiro </TD></TR> 50168515Sgshapiro <TR valign="top"><TD>headerv</TD> 51168515Sgshapiro <TD>The new value of the given header. headerv == NULL implies that the header should be deleted. 52168515Sgshapiro </TD></TR> 53168515Sgshapiro </TABLE> 54168515Sgshapiro</TD></TR> 5590792Sgshapiro 5690792Sgshapiro<!----------- Return values ----------> 57168515Sgshapiro<TR> 58168515Sgshapiro<TH valign="top" align=left>RETURN VALUES</TH> 5990792Sgshapiro 60168515Sgshapiro<TD> 6190792Sgshapirosmfi_chgheader will return MI_FAILURE if 62168515Sgshapiro<UL><LI>headerf is NULL 63168515Sgshapiro <LI>Modifying headers in the current connection state is invalid. 64168515Sgshapiro <LI>Memory allocation fails. 65168515Sgshapiro <LI>A network error occurs. 66168515Sgshapiro <LI>SMFIF_CHGHDRS was not set when <A href="smfi_register.html">smfi_register</A> was called. 67168515Sgshapiro</UL> 6890792SgshapiroOtherwise, it returns MI_SUCCESS. 69168515Sgshapiro</TR> 7090792Sgshapiro 7190792Sgshapiro<!----------- Notes ----------> 72168515Sgshapiro<TR align="left" valign=top> 73168515Sgshapiro<TH>NOTES</TH> 74168515Sgshapiro<TD> 75168515Sgshapiro<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>. 76168515Sgshapiro <LI>A filter which calls smfi_chgheader must have set the SMFIF_CHGHDRS flag in the smfiDesc_str passed to <A href="smfi_register.html">smfi_register</A>. 77168515Sgshapiro <LI>For smfi_chgheader, filter order is important. <B>Later filters will see the header changes made by earlier ones.</B> 78168515Sgshapiro <LI>Neither the name nor the value of the header is checked for 7990792Sgshapiro standards compliance. However, each line of the header must be under 8090792Sgshapiro 2048 characters and should be under 998 characters. If longer headers 8198121Sgshapiro are needed, make them multi-line. To make a multi-line header, insert 82168515Sgshapiro a line feed (ASCII 0x0a, or <TT>\n</TT> in C) followed by at least 8398121Sgshapiro one whitespace character such as a space (ASCII 0x20) or tab (ASCII 0x09, 84168515Sgshapiro or <TT>\t</TT> in C). The line feed should NOT be preceded by a 8598121Sgshapiro carriage return (ASCII 0x0d); the MTA will add this automatically. 86168515Sgshapiro <B>It is the filter writer's responsibility to ensure that no standards 87168515Sgshapiro are violated.</B> 88203004Sgshapiro <LI>The MTA adds a leading space to a header value unless 89203004Sgshapiro the flag 90203004Sgshapiro<A HREF="xxfi_negotiate.html#SMFIP_HDR_LEADSPC"><CODE>SMFIP_HDR_LEADSPC</CODE></A> 91203004Sgshapiro is set, in which case the milter 92203004Sgshapiro must include any desired leading spaces itself. 93168515Sgshapiro</UL> 94168515Sgshapiro</TD> 95168515Sgshapiro</TR> 9690792Sgshapiro 9798121Sgshapiro<!----------- Example code ----------> 98168515Sgshapiro<TR> 99168515Sgshapiro<TH valign="top" align=left>EXAMPLE</TH> 10098121Sgshapiro 101168515Sgshapiro<TD> 102168515Sgshapiro <PRE> 10398121Sgshapiro int ret; 10498121Sgshapiro SMFICTX *ctx; 10598121Sgshapiro 10698121Sgshapiro ... 10798121Sgshapiro 108120256Sgshapiro ret = smfi_chgheader(ctx, "Content-Type", 1, 10998121Sgshapiro "multipart/mixed;\n\tboundary=\"foobar\""); 110168515Sgshapiro </PRE> 111168515Sgshapiro</TD> 112168515Sgshapiro</TR> 11398121Sgshapiro 114168515Sgshapiro</TABLE> 11590792Sgshapiro 116168515Sgshapiro<HR size="1"> 117168515Sgshapiro<FONT size="-1"> 118261363SgshapiroCopyright (c) 2000-2003, 2009 Proofpoint, Inc. and its suppliers. 11990792SgshapiroAll rights reserved. 120168515Sgshapiro<BR> 12190792SgshapiroBy using this file, you agree to the terms and conditions set 122112810Sgshapiroforth in the LICENSE. 123168515Sgshapiro</FONT> 124168515Sgshapiro</BODY> 125168515Sgshapiro</HTML> 126