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