1e92d3f3fSGregory Neil Shapiro<html> 2e92d3f3fSGregory Neil Shapiro<head><title>smfi_insheader</title></head> 3e92d3f3fSGregory Neil Shapiro<body> 4e92d3f3fSGregory Neil Shapiro<!-- 5e92d3f3fSGregory Neil Shapiro$Id: smfi_insheader.html,v 1.3 2004/05/04 16:20:34 gshapiro Exp $ 6e92d3f3fSGregory Neil Shapiro--> 7e92d3f3fSGregory Neil Shapiro<h1>smfi_insheader</h1> 8e92d3f3fSGregory Neil Shapiro 9e92d3f3fSGregory Neil Shapiro<table border="0" cellspacing=4 cellpadding=4> 10e92d3f3fSGregory Neil Shapiro<!---------- Synopsis -----------> 11e92d3f3fSGregory Neil Shapiro<tr><th valign="top" align=left width=150>SYNOPSIS</th><td> 12e92d3f3fSGregory 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); 20e92d3f3fSGregory Neil Shapiro</pre> 21e92d3f3fSGregory Neil ShapiroPrepend a header to the current message. 22e92d3f3fSGregory Neil Shapiro</td></tr> 23e92d3f3fSGregory Neil Shapiro 24e92d3f3fSGregory Neil Shapiro<!----------- Description ----------> 25e92d3f3fSGregory Neil Shapiro<tr><th valign="top" align=left>DESCRIPTION</th><td> 26e92d3f3fSGregory Neil Shapiro<table border="1" cellspacing=1 cellpadding=4> 27e92d3f3fSGregory Neil Shapiro<tr align="left" valign=top> 28e92d3f3fSGregory Neil Shapiro<th width="80">Called When</th> 29e92d3f3fSGregory Neil Shapiro<td>Called only from <a href="xxfi_eom.html">xxfi_eom</a>.</td> 30e92d3f3fSGregory Neil Shapiro</tr> 31e92d3f3fSGregory Neil Shapiro<tr align="left" valign=top> 32e92d3f3fSGregory Neil Shapiro<th width="80">Effects</th> 33e92d3f3fSGregory Neil Shapiro<td>Prepends a header to the current message.</td> 34e92d3f3fSGregory Neil Shapiro</tr> 35e92d3f3fSGregory Neil Shapiro</table> 36e92d3f3fSGregory Neil Shapiro 37e92d3f3fSGregory Neil Shapiro<!----------- Arguments ----------> 38e92d3f3fSGregory Neil Shapiro<tr><th valign="top" align=left>ARGUMENTS</th><td> 39e92d3f3fSGregory Neil Shapiro <table border="1" cellspacing=0> 40e92d3f3fSGregory Neil Shapiro <tr bgcolor="#dddddd"><th>Argument</th><th>Description</th></tr> 41e92d3f3fSGregory Neil Shapiro <tr valign="top"><td>ctx</td> 42e92d3f3fSGregory Neil Shapiro <td>Opaque context structure. 43e92d3f3fSGregory Neil Shapiro </td></tr> 44e92d3f3fSGregory Neil Shapiro <tr valign="top"><td>hdridx</td> 45e92d3f3fSGregory 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. 47e92d3f3fSGregory Neil Shapiro </td></tr> 48e92d3f3fSGregory Neil Shapiro <tr valign="top"><td>headerf</td> 49e92d3f3fSGregory Neil Shapiro <td>The header name, a non-NULL, null-terminated string. 50e92d3f3fSGregory Neil Shapiro </td></tr> 51e92d3f3fSGregory Neil Shapiro <tr valign="top"><td>headerv</td> 52e92d3f3fSGregory Neil Shapiro <td>The header value to be added, a non-NULL, null-terminated string. This may be the empty string. 53e92d3f3fSGregory Neil Shapiro </td></tr> 54e92d3f3fSGregory Neil Shapiro </table> 55e92d3f3fSGregory Neil Shapiro</td></tr> 56e92d3f3fSGregory Neil Shapiro 57e92d3f3fSGregory Neil Shapiro<!----------- Return values ----------> 58e92d3f3fSGregory Neil Shapiro<tr> 59e92d3f3fSGregory Neil Shapiro<th valign="top" align=left>RETURN VALUES</th> 60e92d3f3fSGregory Neil Shapiro 61e92d3f3fSGregory Neil Shapiro<td>smfi_insheader returns MI_FAILURE if: 62e92d3f3fSGregory Neil Shapiro<ul><li>headerf or headerv is NULL. 63e92d3f3fSGregory Neil Shapiro <li>Adding headers in the current connection state is invalid. 64e92d3f3fSGregory Neil Shapiro <li>Memory allocation fails. 65e92d3f3fSGregory Neil Shapiro <li>A network error occurs. 66e92d3f3fSGregory Neil Shapiro <li>SMFIF_ADDHDRS was not set when <a href="smfi_register.html">smfi_register</a> was called. 67e92d3f3fSGregory Neil Shapiro</ul> 68e92d3f3fSGregory Neil ShapiroOtherwise, it returns MI_SUCCESS. 69e92d3f3fSGregory Neil Shapiro</td> 70e92d3f3fSGregory Neil Shapiro</tr> 71e92d3f3fSGregory Neil Shapiro 72e92d3f3fSGregory Neil Shapiro<!----------- Notes ----------> 73e92d3f3fSGregory Neil Shapiro<tr align="left" valign=top> 74e92d3f3fSGregory Neil Shapiro<th>NOTES</th> 75e92d3f3fSGregory Neil Shapiro<td> 76e92d3f3fSGregory Neil Shapiro<ul><li>smfi_insheader does not change a message's existing headers. 77e92d3f3fSGregory Neil ShapiroTo change a header's current value, use <a 78e92d3f3fSGregory Neil Shapirohref="smfi_chgheader.html">smfi_chgheader</a>. 79e92d3f3fSGregory Neil Shapiro <li>A filter which calls smfi_insheader must have set the SMFIF_ADDHDRS flag in the smfiDesc_str passed to <a href="smfi_register.html">smfi_register</a>. 80e92d3f3fSGregory Neil Shapiro <li>For smfi_insheader, filter order is important. <b>Later filters will see the header changes made by earlier ones.</b> 81e92d3f3fSGregory Neil Shapiro <li>If hdridx is a number larger than the number of headers in the message, the header will simply be appended. 82e92d3f3fSGregory Neil Shapiro <li>Neither the name nor the value of the header is checked for 83e92d3f3fSGregory Neil Shapiro standards compliance. However, each line of the header must be under 84e92d3f3fSGregory Neil Shapiro 2048 characters and should be under 998 characters. If longer headers 85e92d3f3fSGregory Neil Shapiro are needed, make them multi-line. To make a multi-line header, insert 86e92d3f3fSGregory Neil Shapiro a line feed (ASCII 0x0a, or <tt>\n</tt> in C) followed by at least 87e92d3f3fSGregory Neil Shapiro one whitespace character such as a space (ASCII 0x20) or tab (ASCII 0x09, 88e92d3f3fSGregory Neil Shapiro or <tt>\t</tt> in C). The line feed should NOT be preceded by a 89e92d3f3fSGregory Neil Shapiro carriage return (ASCII 0x0d); the MTA will add this automatically. 90e92d3f3fSGregory Neil Shapiro <b>It is the filter writer's responsibility to ensure that no standards 91e92d3f3fSGregory Neil Shapiro are violated.</b> 92e92d3f3fSGregory Neil Shapiro</ul> 93e92d3f3fSGregory Neil Shapiro</td> 94e92d3f3fSGregory Neil Shapiro</tr> 95e92d3f3fSGregory Neil Shapiro 96e92d3f3fSGregory Neil Shapiro<!----------- Example code ----------> 97e92d3f3fSGregory Neil Shapiro<tr> 98e92d3f3fSGregory Neil Shapiro<th valign="top" align=left>EXAMPLE</th> 99e92d3f3fSGregory Neil Shapiro 100e92d3f3fSGregory Neil Shapiro<td> 101e92d3f3fSGregory Neil Shapiro <pre> 102e92d3f3fSGregory Neil Shapiro int ret; 103e92d3f3fSGregory Neil Shapiro SMFICTX *ctx; 104e92d3f3fSGregory Neil Shapiro 105e92d3f3fSGregory Neil Shapiro ... 106e92d3f3fSGregory Neil Shapiro 107e92d3f3fSGregory Neil Shapiro ret = smfi_insheader(ctx, 0, "First", "See me?"); 108e92d3f3fSGregory Neil Shapiro </pre> 109e92d3f3fSGregory Neil Shapiro</td> 110e92d3f3fSGregory Neil Shapiro</tr> 111e92d3f3fSGregory Neil Shapiro 112e92d3f3fSGregory Neil Shapiro</table> 113e92d3f3fSGregory Neil Shapiro 114e92d3f3fSGregory Neil Shapiro<hr size="1"> 115e92d3f3fSGregory Neil Shapiro<font size="-1"> 116e92d3f3fSGregory Neil ShapiroCopyright (c) 2004 Sendmail, Inc. and its suppliers. 117e92d3f3fSGregory Neil ShapiroAll rights reserved. 118e92d3f3fSGregory Neil Shapiro<br> 119e92d3f3fSGregory Neil ShapiroBy using this file, you agree to the terms and conditions set 120e92d3f3fSGregory Neil Shapiroforth in the LICENSE. 121e92d3f3fSGregory Neil Shapiro</font> 122e92d3f3fSGregory Neil Shapiro</body> 123e92d3f3fSGregory Neil Shapiro</html> 124