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