1168515Sgshapiro<HTML> 2168515Sgshapiro<HEAD><TITLE>smfi_insheader</TITLE></HEAD> 3168515Sgshapiro<BODY> 4132943Sgshapiro<!-- 5203004Sgshapiro$Id: smfi_insheader.html,v 1.10 2009/05/18 23:51:23 ca Exp $ 6132943Sgshapiro--> 7168515Sgshapiro<H1>smfi_insheader</H1> 8132943Sgshapiro 9168515Sgshapiro<TABLE border="0" cellspacing=4 cellpadding=4> 10132943Sgshapiro<!---------- Synopsis -----------> 11168515Sgshapiro<TR><TH valign="top" align=left width=100>SYNOPSIS</TH><TD> 12168515Sgshapiro<PRE> 13132943Sgshapiro#include <libmilter/mfapi.h> 14132943Sgshapiroint smfi_insheader( 15132943Sgshapiro SMFICTX *ctx, 16132943Sgshapiro int hdridx, 17132943Sgshapiro char *headerf, 18132943Sgshapiro char *headerv 19132943Sgshapiro); 20168515Sgshapiro</PRE> 21132943SgshapiroPrepend a header to the current message. 22168515Sgshapiro</TD></TR> 23132943Sgshapiro 24132943Sgshapiro<!----------- 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>Prepends a header to the current message.</TD> 34168515Sgshapiro</TR> 35168515Sgshapiro</TABLE> 36132943Sgshapiro 37132943Sgshapiro<!----------- 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>hdridx</TD> 45168515Sgshapiro <TD>The location in the internal header list where this header should 46132943Sgshapiro be inserted; 0 makes it the topmost header, etc. 47168515Sgshapiro </TD></TR> 48168515Sgshapiro <TR valign="top"><TD>headerf</TD> 49168515Sgshapiro <TD>The header name, a non-NULL, null-terminated string. 50168515Sgshapiro </TD></TR> 51168515Sgshapiro <TR valign="top"><TD>headerv</TD> 52168515Sgshapiro <TD>The header value to be added, a non-NULL, null-terminated string. This may be the empty string. 53168515Sgshapiro </TD></TR> 54168515Sgshapiro </TABLE> 55168515Sgshapiro</TD></TR> 56132943Sgshapiro 57132943Sgshapiro<!----------- Return values ----------> 58168515Sgshapiro<TR> 59168515Sgshapiro<TH valign="top" align=left>RETURN VALUES</TH> 60132943Sgshapiro 61168515Sgshapiro<TD>smfi_insheader returns MI_FAILURE if: 62168515Sgshapiro<UL><LI>headerf or headerv is NULL. 63168515Sgshapiro <LI>Adding headers in the current connection state is invalid. 64168515Sgshapiro <LI>Memory allocation fails. 65168515Sgshapiro <LI>A network error occurs. 66168515Sgshapiro <LI>SMFIF_ADDHDRS was not set when <A href="smfi_register.html">smfi_register</A> was called. 67168515Sgshapiro</UL> 68132943SgshapiroOtherwise, it returns MI_SUCCESS. 69168515Sgshapiro</TD> 70168515Sgshapiro</TR> 71132943Sgshapiro 72132943Sgshapiro<!----------- Notes ----------> 73168515Sgshapiro<TR align="left" valign=top> 74168515Sgshapiro<TH>NOTES</TH> 75168515Sgshapiro<TD> 76168515Sgshapiro<UL> 77168515Sgshapiro <LI>smfi_insheader does not change a message's existing headers. 78168515Sgshapiro To change a header's current value, use 79168515Sgshapiro <A HREF="smfi_chgheader.html">smfi_chgheader</A>. 80168515Sgshapiro <LI>A filter which calls smfi_insheader must have set the SMFIF_ADDHDRS 81168515Sgshapiro flag in the smfiDesc_str passed to 82168515Sgshapiro <A href="smfi_register.html">smfi_register</A>. 83168515Sgshapiro <LI>For smfi_insheader, filter order is important. 84168515Sgshapiro <B>Later filters will see the header changes made by earlier ones.</B> 85168515Sgshapiro <LI>A filter will receive <EM>only</EM> headers that have been sent 86168515Sgshapiro by the SMTP client and those header modifications by earlier filters. 87168515Sgshapiro It will <EM>not</EM> receive the headers that are inserted by sendmail 88168515Sgshapiro itself. 89168515Sgshapiro This makes the header insertion position highly dependent on 90168515Sgshapiro the headers that exist in the incoming message 91168515Sgshapiro and those that are configured to be added by sendmail. 92168515Sgshapiro For example, sendmail will always add a 93168515Sgshapiro <CODE>Received:</CODE> header to the beginning of the headers. 94168515Sgshapiro Setting <CODE>hdridx</CODE> to 0 will actually insert the header 95168515Sgshapiro before this <CODE>Received:</CODE> header. 96168515Sgshapiro However, later filters can be easily confused as they receive 97168515Sgshapiro the added header, but not the <CODE>Received:</CODE> header, 98168515Sgshapiro thus making it hard to insert a header at a fixed position. 99168515Sgshapiro <LI>If hdridx is a number larger than the number of headers in the message, 100168515Sgshapiro the header will simply be appended. 101168515Sgshapiro <LI>Neither the name nor the value of the header is checked for 102168515Sgshapiro standards compliance. 103168515Sgshapiro However, each line of the header must be under 2048 characters 104168515Sgshapiro and should be under 998 characters. 105168515Sgshapiro If longer headers are needed, make them multi-line. 106168515Sgshapiro To make a multi-line header, 107168515Sgshapiro insert a line feed (ASCII 0x0a, or <TT>\n</TT> in C) 108168515Sgshapiro followed by at least one whitespace character 109168515Sgshapiro such as a space (ASCII 0x20) or tab (ASCII 0x09, or <TT>\t</TT> in C). 110168515Sgshapiro The line feed should NOT be preceded by a carriage return (ASCII 0x0d); 111168515Sgshapiro the MTA will add this automatically. 112168515Sgshapiro <B>It is the filter writer's responsibility to ensure that no standards 113168515Sgshapiro are violated.</B> 114203004Sgshapiro <LI>The MTA adds a leading space to an inserted header value unless 115203004Sgshapiro the flag 116203004Sgshapiro<A HREF="xxfi_negotiate.html#SMFIP_HDR_LEADSPC"><CODE>SMFIP_HDR_LEADSPC</CODE></A> 117203004Sgshapiro is set, in which case the milter 118203004Sgshapiro must include any desired leading spaces itself. 119168515Sgshapiro</UL> 120168515Sgshapiro</TD> 121168515Sgshapiro</TR> 122132943Sgshapiro 123132943Sgshapiro<!----------- Example code ----------> 124168515Sgshapiro<TR> 125168515Sgshapiro<TH valign="top" align=left>EXAMPLE</TH> 126132943Sgshapiro 127168515Sgshapiro<TD> 128168515Sgshapiro <PRE> 129132943Sgshapiro int ret; 130132943Sgshapiro SMFICTX *ctx; 131132943Sgshapiro 132132943Sgshapiro ... 133132943Sgshapiro 134132943Sgshapiro ret = smfi_insheader(ctx, 0, "First", "See me?"); 135168515Sgshapiro </PRE> 136168515Sgshapiro</TD> 137168515Sgshapiro</TR> 138132943Sgshapiro 139168515Sgshapiro</TABLE> 140132943Sgshapiro 141168515Sgshapiro<HR size="1"> 142168515Sgshapiro<FONT size="-1"> 143203004SgshapiroCopyright (c) 2004, 2006, 2009 Sendmail, Inc. and its suppliers. 144132943SgshapiroAll rights reserved. 145168515Sgshapiro<BR> 146132943SgshapiroBy using this file, you agree to the terms and conditions set 147132943Sgshapiroforth in the LICENSE. 148168515Sgshapiro</FONT> 149168515Sgshapiro</BODY> 150168515Sgshapiro</HTML> 151