smfi_insheader.3n (2010 09)
s
smfi_insheader(3N) smfi_insheader(3N)
NAME
smfi_insheader() - prepends a header to the current sendmail message
SYNOPSIS
#include <libmilter/mfapi.h>
int smfi_insheader(
SMFICTX *ctx,
int hdridx,
char *headerf ,
char *headerv
);
PARAMETERS
ctx Specifies the opaque context structure.
hdridx Specifies the location in the internal header list where the header must be inserted. A value of
0 (zero) places the header in the beginning of the header.
headerf Specifies the header name, which is a non-NULL, null-terminated string.
headerv Specifies the header value to be added. A header value is a non-NULL, null-terminated string
and can be an empty string.
DESCRIPTION
smfi_insheader() prepends a header to the current message.
smfi_insheader() can be called
only from the
xxfi_eom() function.
Notes
•
smfi_insheader()
does not change existing headers of a message. To change the current value of
a header, use the
smfi_chgheader()
routine.
• A filter that calls
smfi_insheader()
must set the SMFIF_ADDHDRS flag in the smfiDesc_str
structure passed to the smfi_register()
routine.
• For the
smfi_insheader()
filter, the order in which filters are placed is imporant. Filters placed
later in the sequence will observe the changes already done by the earlier filters.
• If the value of hdridx larger than the number of headers in the message, the header is simply be
appended.
• The name and the value of the header are not checked for standards compliance. However, each line
of the header must be under 2048 characters. If longer headers are needed, multi-line header must be
used. To make a multi-line header, insert a linefeed (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 linefeed
must not be preceded by a carriage return (ASCII 0x0d); the MTA adds this automatically. It is the
responsibility of the filter writer to ensure that standards are not violated.
RETURN VALUE
smfi_insheader() returns MI_FAILURE due to the following reasons:
• The headerf or headerv value is NULL.
• Adding headers in the current connection state is invalid.
• Memory allocation fails.
• Network error occurs.
•
SMFIF_ADDHDRS is not set when smfi_register() is called.
smfi_insheader() returns MI_SUCCESS on success.
EXAMPLES
int ret;
SMFICTX *ctx;
...
ret = smfi_insheader(ctx, 0, "First", "See me?");
HP-UX 11i Version 3: September 2010 − 1 − Hewlett-Packard Company 1