smfi_insheader Function
Purpose
The smfi_insheader function prepends a header to the current message.
Syntax
#include <libmilter/mfapi.h>
int smfi_insheader(
SMFICTX ,
int hdridx,
char *headerf,
char *headerv
);Description
The smfi_insheader function is called from the xxfi_eom function, to prepend a header to the current message.
The smfi_insheader function does not modify the existing headers of a message.
To change the current value of a header, use the smfi_chgheader function.
A
filter that calls the smfi_insheader function must set the SMFIF_ADDHDRS flag
in the smfiDesc_str argument, which is passed in
the smfi_register function.
The smfi_insheader function requires the filter order to be specified. You can view the modifications in the header by using the filters that were created earlier.
A filter receives headers that are sent by the simple mail transfer protocol (SMTP) client and also the headers modified by the earlier filters. The headers inserted by the sendmail command and headers inserted by itself are not received. The position to insert the header is dependent on the headers existing in the incoming message and also on the headers that are configured to be added by the sendmail command.
For
example, the sendmail command always adds a Received: header at
the beginning of the header. On setting the hdridx value to 0,
the header is inserted before the Received: header parameter.
However, the filters later get misled as they receive the added header,
but not the Received: header, thus making it hard to insert
a header at a fixed position.
If the hdridx value is greater than the number of headers in the message, the header is appended.
The
name or the value of the header is not checked for standards compliance.
However, each line of the header must be below 998 characters. If
you require longer header names, use a multi-line header. If you must
create a multi-line header, insert a line feed (ASCII 0x0a,
or \n in C programming language) followed by a whitespace
character such as a space (ASCII 0x20) or tab (ASCII
0x09, or \t in C programming language).
The line feed cannot be preceded by a carriage return (ASCII
0x0d). The mail transfer agent (MTA) adds the carriage return
automatically. The filter writers responsibility must ensure that
no standards are violated.
The MTA adds a leading space to an inserted header value unless the SMFIP_HDR_LEADSPC flag is set, in which case the milter parameter must include any desired leading spaces.
Arguments
| Item | Description |
|---|---|
| ctx | The opaque context structure is maintained in the libmilter parameter. |
| headerf | The header name is a null-terminated string that is not NULL. |
| headerv | The header value to be added, can be a non-NULL null-terminated string or an empty string. |
Return values
- The headerf or headerv argument is NULL.
- Adding headers in the current connection state is invalid.
- The memory allocation fails.
- A network error occurs.
- The SMFIF_ADDHDRS flag was not set when smfi_register function was called.
Example
int ret;
SMFICTX *ctx;
...
ret = smfi_insheader( ctx, 0, "First", "See me?");;