smfi_addheader.html revision 168515
1168515Sgshapiro<HTML> 2168515Sgshapiro<HEAD><TITLE>smfi_addheader</TITLE></HEAD> 3168515Sgshapiro<BODY> 4132943Sgshapiro<!-- 5168515Sgshapiro$Id: smfi_addheader.html,v 1.19 2006/12/21 18:30:35 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 <libmilter/mfapi.h> 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> 93168515Sgshapiro <LI>The MTA adds a leading space to an added header value. 94168515Sgshapiro</UL> 95168515Sgshapiro</TD> 96168515Sgshapiro</TR> 9790792Sgshapiro 9898121Sgshapiro<!----------- Example code ----------> 99168515Sgshapiro<TR> 100168515Sgshapiro<TH valign="top" align=left>EXAMPLE</TH> 10198121Sgshapiro 102168515Sgshapiro<TD> 103168515Sgshapiro <PRE> 10498121Sgshapiro int ret; 10598121Sgshapiro SMFICTX *ctx; 10698121Sgshapiro 10798121Sgshapiro ... 10898121Sgshapiro 10998121Sgshapiro ret = smfi_addheader(ctx, "Content-Type", 11098121Sgshapiro "multipart/mixed;\n\tboundary=\"foobar\""); 111168515Sgshapiro </PRE> 112168515Sgshapiro</TD> 113168515Sgshapiro</TR> 11498121Sgshapiro 115168515Sgshapiro</TABLE> 11690792Sgshapiro 117168515Sgshapiro<HR size="1"> 118168515Sgshapiro<FONT size="-1"> 119168515SgshapiroCopyright (c) 2000-2003, 2006 Sendmail, Inc. and its suppliers. 12090792SgshapiroAll rights reserved. 121168515Sgshapiro<BR> 12290792SgshapiroBy using this file, you agree to the terms and conditions set 123112810Sgshapiroforth in the LICENSE. 124168515Sgshapiro</FONT> 125168515Sgshapiro</BODY> 126168515Sgshapiro</HTML> 127