xref: /freebsd/contrib/sendmail/libmilter/docs/smfi_chgheader.html (revision e2c0e292e8a7ca00ba99bcfccc9e637f45c3e8b1)
1d0cef73dSGregory Neil Shapiro<HTML>
2d0cef73dSGregory Neil Shapiro<HEAD><TITLE>smfi_chgheader</TITLE></HEAD>
3d0cef73dSGregory Neil Shapiro<BODY>
4e92d3f3fSGregory Neil Shapiro<!--
54313cc83SGregory Neil Shapiro$Id: smfi_chgheader.html,v 1.19 2013-11-22 20:51:39 ca Exp $
6e92d3f3fSGregory Neil Shapiro-->
7d0cef73dSGregory Neil Shapiro<H1>smfi_chgheader</H1>
840266059SGregory Neil Shapiro
9d0cef73dSGregory Neil Shapiro<TABLE border="0" cellspacing=4 cellpadding=4>
1040266059SGregory Neil Shapiro<!---------- Synopsis ----------->
11d0cef73dSGregory Neil Shapiro<TR><TH valign="top" align=left width=100>SYNOPSIS</TH><TD>
12d0cef73dSGregory Neil Shapiro<PRE>
1340266059SGregory Neil Shapiro#include &lt;libmilter/mfapi.h&gt;
1440266059SGregory Neil Shapiroint smfi_chgheader(
1540266059SGregory Neil Shapiro	SMFICTX *ctx,
1640266059SGregory Neil Shapiro	char *headerf,
1740266059SGregory Neil Shapiro	mi_int32 hdridx,
1840266059SGregory Neil Shapiro	char *headerv
1940266059SGregory Neil Shapiro);
20d0cef73dSGregory Neil Shapiro</PRE>
2140266059SGregory Neil ShapiroChange or delete a message header.
22d0cef73dSGregory Neil Shapiro</TD></TR>
2340266059SGregory Neil Shapiro
2440266059SGregory 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>Changes a header's value for the current message.</TD>
34d0cef73dSGregory Neil Shapiro</TR>
35d0cef73dSGregory Neil Shapiro</TABLE>
36*5b0945b5SGregory Neil Shapiro</TD></TR>
3740266059SGregory Neil Shapiro
3840266059SGregory 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>headerf</TD>
46d0cef73dSGregory Neil Shapiro	<TD>The header name, a non-NULL, null-terminated string.
47d0cef73dSGregory Neil Shapiro	</TD></TR>
48d0cef73dSGregory Neil Shapiro    <TR valign="top"><TD>hdridx</TD>
49d0cef73dSGregory Neil Shapiro	<TD>Header index value (1-based). A hdridx value of 1 will modify the first occurrence of a header named headerf.  If hdridx is greater than the number of times headerf appears, a new copy of headerf will be added.
50d0cef73dSGregory Neil Shapiro	</TD></TR>
51d0cef73dSGregory Neil Shapiro    <TR valign="top"><TD>headerv</TD>
52d0cef73dSGregory Neil Shapiro	<TD>The new value of the given header.  headerv == NULL implies that the header should be deleted.
53d0cef73dSGregory Neil Shapiro	</TD></TR>
54d0cef73dSGregory Neil Shapiro    </TABLE>
55d0cef73dSGregory Neil Shapiro</TD></TR>
5640266059SGregory Neil Shapiro
5740266059SGregory Neil Shapiro<!----------- Return values ---------->
58d0cef73dSGregory Neil Shapiro<TR>
59d0cef73dSGregory Neil Shapiro<TH valign="top" align=left>RETURN VALUES</TH>
6040266059SGregory Neil Shapiro
61d0cef73dSGregory Neil Shapiro<TD>
6240266059SGregory Neil Shapirosmfi_chgheader will return MI_FAILURE if
63d0cef73dSGregory Neil Shapiro<UL><LI>headerf is NULL
64d0cef73dSGregory Neil Shapiro    <LI>Modifying 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_CHGHDRS">SMFIF_CHGHDRS</A> is not set.
68d0cef73dSGregory Neil Shapiro</UL>
6940266059SGregory Neil ShapiroOtherwise, it returns MI_SUCCESS.
70*5b0945b5SGregory Neil Shapiro</TD></TR>
7140266059SGregory Neil Shapiro
7240266059SGregory 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><LI>While smfi_chgheader may be used to add new headers, it is more efficient and far safer to use <A href="smfi_addheader.html">smfi_addheader</A>.
77*5b0945b5SGregory Neil Shapiro    <LI>A filter which calls smfi_chgheader must have set the
78*5b0945b5SGregory Neil Shapiro        <A HREF="smfi_register.html#SMFIF_CHGHDRS">SMFIF_CHGHDRS</A> flag.
79d0cef73dSGregory Neil Shapiro    <LI>For smfi_chgheader, filter order is important.  <B>Later filters will see the header changes made by earlier ones.</B>
80d0cef73dSGregory Neil Shapiro    <LI>Neither the name nor the value of the header is checked for
8140266059SGregory Neil Shapiro    standards compliance.  However, each line of the header must be under
8240266059SGregory Neil Shapiro    2048 characters and should be under 998 characters.  If longer headers
8394c01205SGregory Neil Shapiro    are needed, make them multi-line.  To make a multi-line header, insert
84d0cef73dSGregory Neil Shapiro    a line feed (ASCII 0x0a, or <TT>\n</TT> in C) followed by at least
8594c01205SGregory Neil Shapiro    one whitespace character such as a space (ASCII 0x20) or tab (ASCII 0x09,
86d0cef73dSGregory Neil Shapiro    or <TT>\t</TT> in C).  The line feed should NOT be preceded by a
8794c01205SGregory Neil Shapiro    carriage return (ASCII 0x0d); the MTA will add this automatically.
88d0cef73dSGregory Neil Shapiro    <B>It is the filter writer's responsibility to ensure that no standards
89d0cef73dSGregory Neil Shapiro    are violated.</B>
909bd497b8SGregory Neil Shapiro    <LI>The MTA adds a leading space to a header value unless
919bd497b8SGregory Neil Shapiro    the flag
929bd497b8SGregory Neil Shapiro<A HREF="xxfi_negotiate.html#SMFIP_HDR_LEADSPC"><CODE>SMFIP_HDR_LEADSPC</CODE></A>
939bd497b8SGregory Neil Shapiro    is set, in which case the milter
949bd497b8SGregory Neil Shapiro    must include any desired leading spaces itself.
95d0cef73dSGregory Neil Shapiro</UL>
96d0cef73dSGregory Neil Shapiro</TD>
97d0cef73dSGregory Neil Shapiro</TR>
9840266059SGregory Neil Shapiro
9994c01205SGregory Neil Shapiro<!----------- Example code ---------->
100d0cef73dSGregory Neil Shapiro<TR>
101d0cef73dSGregory Neil Shapiro<TH valign="top" align=left>EXAMPLE</TH>
10294c01205SGregory Neil Shapiro
103d0cef73dSGregory Neil Shapiro<TD>
104d0cef73dSGregory Neil Shapiro <PRE>
10594c01205SGregory Neil Shapiro  int ret;
10694c01205SGregory Neil Shapiro  SMFICTX *ctx;
10794c01205SGregory Neil Shapiro
10894c01205SGregory Neil Shapiro  ...
10994c01205SGregory Neil Shapiro
110a7ec597cSGregory Neil Shapiro  ret = smfi_chgheader(ctx, "Content-Type", 1,
11194c01205SGregory Neil Shapiro                       "multipart/mixed;\n\tboundary=\"foobar\"");
112d0cef73dSGregory Neil Shapiro </PRE>
113d0cef73dSGregory Neil Shapiro</TD>
114d0cef73dSGregory Neil Shapiro</TR>
11594c01205SGregory Neil Shapiro
116d0cef73dSGregory Neil Shapiro</TABLE>
11740266059SGregory Neil Shapiro
118d0cef73dSGregory Neil Shapiro<HR size="1">
119d0cef73dSGregory Neil Shapiro<FONT size="-1">
1205dd76dd0SGregory Neil ShapiroCopyright (c) 2000-2003, 2009 Proofpoint, Inc. and its suppliers.
12140266059SGregory Neil ShapiroAll rights reserved.
122d0cef73dSGregory Neil Shapiro<BR>
12340266059SGregory Neil ShapiroBy using this file, you agree to the terms and conditions set
1245ef517c0SGregory Neil Shapiroforth in the LICENSE.
125d0cef73dSGregory Neil Shapiro</FONT>
126d0cef73dSGregory Neil Shapiro</BODY>
127d0cef73dSGregory Neil Shapiro</HTML>
128