smfi_addheader.html revision 132943
190792Sgshapiro<html> 290792Sgshapiro<head><title>smfi_addheader</title></head> 390792Sgshapiro<body> 4132943Sgshapiro<!-- 5132943Sgshapiro$Id: smfi_addheader.html,v 1.15 2004/05/04 17:55:50 ca Exp $ 6132943Sgshapiro--> 790792Sgshapiro<h1>smfi_addheader</h1> 890792Sgshapiro 990792Sgshapiro<table border="0" cellspacing=4 cellpadding=4> 1090792Sgshapiro<!---------- Synopsis -----------> 1190792Sgshapiro<tr><th valign="top" align=left width=150>SYNOPSIS</th><td> 1290792Sgshapiro<pre> 1390792Sgshapiro#include <libmilter/mfapi.h> 1490792Sgshapiroint smfi_addheader( 1590792Sgshapiro SMFICTX *ctx, 1690792Sgshapiro char *headerf, 1790792Sgshapiro char *headerv 1890792Sgshapiro); 1990792Sgshapiro</pre> 2090792SgshapiroAdd a header to the current message. 2190792Sgshapiro</td></tr> 2290792Sgshapiro 2390792Sgshapiro<!----------- Description ----------> 2490792Sgshapiro<tr><th valign="top" align=left>DESCRIPTION</th><td> 2590792Sgshapiro<table border="1" cellspacing=1 cellpadding=4> 2690792Sgshapiro<tr align="left" valign=top> 2790792Sgshapiro<th width="80">Called When</th> 2890792Sgshapiro<td>Called only from <a href="xxfi_eom.html">xxfi_eom</a>.</td> 2990792Sgshapiro</tr> 3090792Sgshapiro<tr align="left" valign=top> 3190792Sgshapiro<th width="80">Effects</th> 3290792Sgshapiro<td>Adds a header to the current message.</td> 3390792Sgshapiro</tr> 3490792Sgshapiro</table> 3590792Sgshapiro 3690792Sgshapiro<!----------- Arguments ----------> 3790792Sgshapiro<tr><th valign="top" align=left>ARGUMENTS</th><td> 3890792Sgshapiro <table border="1" cellspacing=0> 3990792Sgshapiro <tr bgcolor="#dddddd"><th>Argument</th><th>Description</th></tr> 4090792Sgshapiro <tr valign="top"><td>ctx</td> 4190792Sgshapiro <td>Opaque context structure. 4290792Sgshapiro </td></tr> 4390792Sgshapiro <tr valign="top"><td>headerf</td> 4490792Sgshapiro <td>The header name, a non-NULL, null-terminated string. 4590792Sgshapiro </td></tr> 4690792Sgshapiro <tr valign="top"><td>headerv</td> 4790792Sgshapiro <td>The header value to be added, a non-NULL, null-terminated string. This may be the empty string. 4890792Sgshapiro </td></tr> 4990792Sgshapiro </table> 5090792Sgshapiro</td></tr> 5190792Sgshapiro 5290792Sgshapiro<!----------- Return values ----------> 5390792Sgshapiro<tr> 5490792Sgshapiro<th valign="top" align=left>RETURN VALUES</th> 5590792Sgshapiro 5690792Sgshapiro<td>smfi_addheader returns MI_FAILURE if: 5790792Sgshapiro<ul><li>headerf or headerv is NULL. 5890792Sgshapiro <li>Adding headers in the current connection state is invalid. 5990792Sgshapiro <li>Memory allocation fails. 6090792Sgshapiro <li>A network error occurs. 6190792Sgshapiro <li>SMFIF_ADDHDRS was not set when <a href="smfi_register.html">smfi_register</a> was called. 6290792Sgshapiro</ul> 6390792SgshapiroOtherwise, it returns MI_SUCCESS. 6490792Sgshapiro</td> 6590792Sgshapiro</tr> 6690792Sgshapiro 6790792Sgshapiro<!----------- Notes ----------> 6890792Sgshapiro<tr align="left" valign=top> 6990792Sgshapiro<th>NOTES</th> 7090792Sgshapiro<td> 7190792Sgshapiro<ul><li>smfi_addheader does not change a message's existing headers. 7290792SgshapiroTo change a header's current value, use <a 7390792Sgshapirohref="smfi_chgheader.html">smfi_chgheader</a>. 7490792Sgshapiro <li>A filter which calls smfi_addheader must have set the SMFIF_ADDHDRS flag in the smfiDesc_str passed to <a href="smfi_register.html">smfi_register</a>. 75132943Sgshapiro <li>For smfi_addheader, filter order is important. <b>Later filters will see the header changes made by earlier ones.</b> 7690792Sgshapiro <li>Neither the name nor the value of the header is checked for 7790792Sgshapiro standards compliance. However, each line of the header must be under 7890792Sgshapiro 2048 characters and should be under 998 characters. If longer headers 7998121Sgshapiro are needed, make them multi-line. To make a multi-line header, insert 8098121Sgshapiro a line feed (ASCII 0x0a, or <tt>\n</tt> in C) followed by at least 8198121Sgshapiro one whitespace character such as a space (ASCII 0x20) or tab (ASCII 0x09, 8298121Sgshapiro or <tt>\t</tt> in C). The line feed should NOT be preceded by a 8398121Sgshapiro carriage return (ASCII 0x0d); the MTA will add this automatically. 8490792Sgshapiro <b>It is the filter writer's responsibility to ensure that no standards 8590792Sgshapiro are violated.</b> 8690792Sgshapiro</ul> 8790792Sgshapiro</td> 8890792Sgshapiro</tr> 8990792Sgshapiro 9098121Sgshapiro<!----------- Example code ----------> 9198121Sgshapiro<tr> 9298121Sgshapiro<th valign="top" align=left>EXAMPLE</th> 9398121Sgshapiro 9498121Sgshapiro<td> 9598121Sgshapiro <pre> 9698121Sgshapiro int ret; 9798121Sgshapiro SMFICTX *ctx; 9898121Sgshapiro 9998121Sgshapiro ... 10098121Sgshapiro 10198121Sgshapiro ret = smfi_addheader(ctx, "Content-Type", 10298121Sgshapiro "multipart/mixed;\n\tboundary=\"foobar\""); 10398121Sgshapiro </pre> 10498121Sgshapiro</td> 10598121Sgshapiro</tr> 10698121Sgshapiro 10790792Sgshapiro</table> 10890792Sgshapiro 10990792Sgshapiro<hr size="1"> 11090792Sgshapiro<font size="-1"> 111112810SgshapiroCopyright (c) 2000-2003 Sendmail, Inc. and its suppliers. 11290792SgshapiroAll rights reserved. 11390792Sgshapiro<br> 11490792SgshapiroBy using this file, you agree to the terms and conditions set 115112810Sgshapiroforth in the LICENSE. 11690792Sgshapiro</font> 11790792Sgshapiro</body> 11890792Sgshapiro</html> 119