contrib/sendmail/libmilter/docs/smfi_insheader.html

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