diff options
Diffstat (limited to 'contrib/sendmail/libmilter/docs/smfi_insheader.html')
| -rw-r--r-- | contrib/sendmail/libmilter/docs/smfi_insheader.html | 194 |
1 files changed, 108 insertions, 86 deletions
diff --git a/contrib/sendmail/libmilter/docs/smfi_insheader.html b/contrib/sendmail/libmilter/docs/smfi_insheader.html index 837a1fd..a4ba77f 100644 --- a/contrib/sendmail/libmilter/docs/smfi_insheader.html +++ b/contrib/sendmail/libmilter/docs/smfi_insheader.html @@ -1,15 +1,15 @@ -<html> -<head><title>smfi_insheader</title></head> -<body> +<HTML> +<HEAD><TITLE>smfi_insheader</TITLE></HEAD> +<BODY> <!-- -$Id: smfi_insheader.html,v 1.3 2004/05/04 16:20:34 gshapiro Exp $ +$Id: smfi_insheader.html,v 1.9 2006/12/21 18:30:35 ca Exp $ --> -<h1>smfi_insheader</h1> +<H1>smfi_insheader</H1> -<table border="0" cellspacing=4 cellpadding=4> +<TABLE border="0" cellspacing=4 cellpadding=4> <!---------- Synopsis -----------> -<tr><th valign="top" align=left width=150>SYNOPSIS</th><td> -<pre> +<TR><TH valign="top" align=left width=100>SYNOPSIS</TH><TD> +<PRE> #include <libmilter/mfapi.h> int smfi_insheader( SMFICTX *ctx, @@ -17,107 +17,129 @@ int smfi_insheader( char *headerf, char *headerv ); -</pre> +</PRE> Prepend a header to the current message. -</td></tr> +</TD></TR> <!----------- Description ----------> -<tr><th valign="top" align=left>DESCRIPTION</th><td> -<table border="1" cellspacing=1 cellpadding=4> -<tr align="left" valign=top> -<th width="80">Called When</th> -<td>Called only from <a href="xxfi_eom.html">xxfi_eom</a>.</td> -</tr> -<tr align="left" valign=top> -<th width="80">Effects</th> -<td>Prepends a header to the current message.</td> -</tr> -</table> +<TR><TH valign="top" align=left>DESCRIPTION</TH><TD> +<TABLE border="1" cellspacing=1 cellpadding=4> +<TR align="left" valign=top> +<TH width="80">Called When</TH> +<TD>Called only from <A href="xxfi_eom.html">xxfi_eom</A>.</TD> +</TR> +<TR align="left" valign=top> +<TH width="80">Effects</TH> +<TD>Prepends a header to the current message.</TD> +</TR> +</TABLE> <!----------- Arguments ----------> -<tr><th valign="top" align=left>ARGUMENTS</th><td> - <table border="1" cellspacing=0> - <tr bgcolor="#dddddd"><th>Argument</th><th>Description</th></tr> - <tr valign="top"><td>ctx</td> - <td>Opaque context structure. - </td></tr> - <tr valign="top"><td>hdridx</td> - <td>The location in the internal header list where this header should +<TR><TH valign="top" align=left>ARGUMENTS</TH><TD> + <TABLE border="1" cellspacing=0> + <TR bgcolor="#dddddd"><TH>Argument</TH><TH>Description</TH></TR> + <TR valign="top"><TD>ctx</TD> + <TD>Opaque context structure. + </TD></TR> + <TR valign="top"><TD>hdridx</TD> + <TD>The location in the internal header list where this header should be inserted; 0 makes it the topmost header, etc. - </td></tr> - <tr valign="top"><td>headerf</td> - <td>The header name, a non-NULL, null-terminated string. - </td></tr> - <tr valign="top"><td>headerv</td> - <td>The header value to be added, a non-NULL, null-terminated string. This may be the empty string. - </td></tr> - </table> -</td></tr> + </TD></TR> + <TR valign="top"><TD>headerf</TD> + <TD>The header name, a non-NULL, null-terminated string. + </TD></TR> + <TR valign="top"><TD>headerv</TD> + <TD>The header value to be added, a non-NULL, null-terminated string. This may be the empty string. + </TD></TR> + </TABLE> +</TD></TR> <!----------- Return values ----------> -<tr> -<th valign="top" align=left>RETURN VALUES</th> +<TR> +<TH valign="top" align=left>RETURN VALUES</TH> -<td>smfi_insheader returns MI_FAILURE if: -<ul><li>headerf or headerv is NULL. - <li>Adding headers in the current connection state is invalid. - <li>Memory allocation fails. - <li>A network error occurs. - <li>SMFIF_ADDHDRS was not set when <a href="smfi_register.html">smfi_register</a> was called. -</ul> +<TD>smfi_insheader returns MI_FAILURE if: +<UL><LI>headerf or headerv is NULL. + <LI>Adding headers in the current connection state is invalid. + <LI>Memory allocation fails. + <LI>A network error occurs. + <LI>SMFIF_ADDHDRS was not set when <A href="smfi_register.html">smfi_register</A> was called. +</UL> Otherwise, it returns MI_SUCCESS. -</td> -</tr> +</TD> +</TR> <!----------- Notes ----------> -<tr align="left" valign=top> -<th>NOTES</th> -<td> -<ul><li>smfi_insheader does not change a message's existing headers. -To change a header's current value, use <a -href="smfi_chgheader.html">smfi_chgheader</a>. - <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>. - <li>For smfi_insheader, filter order is important. <b>Later filters will see the header changes made by earlier ones.</b> - <li>If hdridx is a number larger than the number of headers in the message, the header will simply be appended. - <li>Neither the name nor the value of the header is checked for - standards compliance. However, each line of the header must be under - 2048 characters and should be under 998 characters. If longer headers - are needed, make them multi-line. To make a multi-line header, insert - a line feed (ASCII 0x0a, or <tt>\n</tt> in C) followed by at least - one whitespace character such as a space (ASCII 0x20) or tab (ASCII 0x09, - or <tt>\t</tt> in C). The line feed should NOT be preceded by a - carriage return (ASCII 0x0d); the MTA will add this automatically. - <b>It is the filter writer's responsibility to ensure that no standards - are violated.</b> -</ul> -</td> -</tr> +<TR align="left" valign=top> +<TH>NOTES</TH> +<TD> +<UL> + <LI>smfi_insheader does not change a message's existing headers. + To change a header's current value, use + <A HREF="smfi_chgheader.html">smfi_chgheader</A>. + <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>. + <LI>For smfi_insheader, filter order is important. + <B>Later filters will see the header changes made by earlier ones.</B> + <LI>A filter will receive <EM>only</EM> headers that have been sent + by the SMTP client and those header modifications by earlier filters. + It will <EM>not</EM> receive the headers that are inserted by sendmail + itself. + This makes the header insertion position highly dependent on + the headers that exist in the incoming message + and those that are configured to be added by sendmail. + For example, sendmail will always add a + <CODE>Received:</CODE> header to the beginning of the headers. + Setting <CODE>hdridx</CODE> to 0 will actually insert the header + before this <CODE>Received:</CODE> header. + However, later filters can be easily confused as they receive + the added header, but not the <CODE>Received:</CODE> header, + thus making it hard to insert a header at a fixed position. + <LI>If hdridx is a number larger than the number of headers in the message, + the header will simply be appended. + <LI>Neither the name nor the value of the header is checked for + standards compliance. + However, each line of the header must be under 2048 characters + and should be under 998 characters. + If longer headers are needed, make them multi-line. + To make a multi-line header, + insert a line feed (ASCII 0x0a, or <TT>\n</TT> in C) + followed by at least one whitespace character + such as a space (ASCII 0x20) or tab (ASCII 0x09, or <TT>\t</TT> in C). + The line feed should NOT be preceded by a carriage return (ASCII 0x0d); + the MTA will add this automatically. + <B>It is the filter writer's responsibility to ensure that no standards + are violated.</B> +</UL> +</TD> +</TR> <!----------- Example code ----------> -<tr> -<th valign="top" align=left>EXAMPLE</th> +<TR> +<TH valign="top" align=left>EXAMPLE</TH> -<td> - <pre> +<TD> + <PRE> int ret; SMFICTX *ctx; ... ret = smfi_insheader(ctx, 0, "First", "See me?"); - </pre> -</td> -</tr> + </PRE> +</TD> +</TR> -</table> +</TABLE> -<hr size="1"> -<font size="-1"> -Copyright (c) 2004 Sendmail, Inc. and its suppliers. +<HR size="1"> +<FONT size="-1"> +Copyright (c) 2004, 2006 Sendmail, Inc. and its suppliers. All rights reserved. -<br> +<BR> By using this file, you agree to the terms and conditions set forth in the LICENSE. -</font> -</body> -</html> +</FONT> +</BODY> +</HTML> |
