smfi_insheader

SYNOPSIS

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

Prepend a header to the current message.

DESCRIPTION

Called When	Called only from xxfi_eom.
Effects	Prepends a header to the current message.

ARGUMENTS

Argument	Description
ctx	Opaque context structure.
hdridx	The location in the internal header list where this header should be inserted; 0 makes it the topmost header, etc.
headerf	The header name, a non-NULL, null-terminated string.
headerv	The header value to be added, a non-NULL, null-terminated string. This may be the empty string.

RETURN VALUES

smfi_insheader returns MI_FAILURE if:

headerf or headerv is NULL.
Adding headers in the current connection state is invalid.
Memory allocation fails.
A network error occurs.
SMFIF_ADDHDRS was not set when smfi_register was called.

Otherwise, it returns MI_SUCCESS.

NOTES

smfi_insheader does not change a message's existing headers. To change a header's current value, use smfi_chgheader.
A filter which calls smfi_insheader must have set the SMFIF_ADDHDRS flag in the smfiDesc_str passed to smfi_register.
For smfi_insheader, filter order is important. Later filters will see the header changes made by earlier ones.
A filter will receive only headers that have been sent by the SMTP client and those header modifications by earlier filters. It will not 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 Received: header to the beginning of the headers. Setting hdridx to 0 will actually insert the header before this Received: header. However, later filters can be easily confused as they receive the added header, but not the Received: header, thus making it hard to insert a header at a fixed position.
If hdridx is a number larger than the number of headers in the message, the header will simply be appended.
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 \n in C) followed by at least one whitespace character such as a space (ASCII 0x20) or tab (ASCII 0x09, or \t in C). The line feed should NOT be preceded by a carriage return (ASCII 0x0d); the MTA will add this automatically. It is the filter writer's responsibility to ensure that no standards are violated.
The MTA adds a leading space to an inserted header value unless the flag SMFIP_HDR_LEADSPC is set, in which case the milter must include any desired leading spaces itself.

EXAMPLE

  int ret;
  SMFICTX *ctx;

  ...

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