1<html> 2<head><title>smfi_insheader</title></head> 3<body> 4<!-- 5$Id: smfi_insheader.html,v 1.3 2004/05/04 16:20:34 gshapiro 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=150>SYNOPSIS</th><td> 12<pre> 13#include <libmilter/mfapi.h> 14int smfi_insheader( 15 SMFICTX *ctx, 16 int hdridx, 17 char *headerf, 18 char *headerv 19); 20</pre> 21Prepend 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> 68Otherwise, 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><li>smfi_insheader does not change a message's existing headers. 77To change a header's current value, use <a 78href="smfi_chgheader.html">smfi_chgheader</a>. 79 <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>. 80 <li>For smfi_insheader, filter order is important. <b>Later filters will see the header changes made by earlier ones.</b> 81 <li>If hdridx is a number larger than the number of headers in the message, the header will simply be appended. 82 <li>Neither the name nor the value of the header is checked for 83 standards compliance. However, each line of the header must be under 84 2048 characters and should be under 998 characters. If longer headers 85 are needed, make them multi-line. To make a multi-line header, insert 86 a line feed (ASCII 0x0a, or <tt>\n</tt> in C) followed by at least 87 one whitespace character such as a space (ASCII 0x20) or tab (ASCII 0x09, 88 or <tt>\t</tt> in C). The line feed should NOT be preceded by a 89 carriage return (ASCII 0x0d); the MTA will add this automatically. 90 <b>It is the filter writer's responsibility to ensure that no standards 91 are violated.</b> 92</ul> 93</td> 94</tr> 95 96<!----------- Example code ----------> 97<tr> 98<th valign="top" align=left>EXAMPLE</th> 99 100<td> 101 <pre> 102 int ret; 103 SMFICTX *ctx; 104 105 ... 106 107 ret = smfi_insheader(ctx, 0, "First", "See me?"); 108 </pre> 109</td> 110</tr> 111 112</table> 113 114<hr size="1"> 115<font size="-1"> 116Copyright (c) 2004 Sendmail, Inc. and its suppliers. 117All rights reserved. 118<br> 119By using this file, you agree to the terms and conditions set 120forth in the LICENSE. 121</font> 122</body> 123</html> 124