smfi_insheader Function


The smfi_insheader function prepends a header to the current message.


#include <libmilter/mfapi.h>
int smfi_insheader(
int hdridx,
char *headerf,
char *headerv


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.


Table 1. 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 smfi_insheader function returns the MI_FAILURE value in the following cases, else the function returns MI_SUCCESS.
  • 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.


int ret;
ret = smfi_insheader( ctx, 0, "First", "See me?");;

Related information