smfi_chgheader Function
Purpose
The smfi_chgheader function modifies or deletes a message header.
Syntax
#include <libmilter/mfapi.h>
int smfi_chgheader(
SMFICTX *ctx,
char *headerf,
mi_int32 hdridx,
char *headerv
);Description
The smfi_chgheader function is called from the xxfi_eom function to modify a headers value for the current message.
The smfi_chgheader function can be used to add new headers. However, it is efficient and safer to use the smfi_addheader function.
A filter that calls
the smfi_chgheader function must set the SMFIF_CHGHDRS flag
in the smfiDesc_str argument. The filter then passes
the value to the smfi_register function.
The smfi_chgheader function requires the filter order to be specified. You can view the modifications in the header by using the filters that were created earlier.
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), mail transfer agent (MTA) adds it automatically. The
filter writers responsibility must ensure that no standards are violated.
The MTA adds a leading space to an added header value unless the flag SMFIP_HDR_LEADSPC is set, in which case the milter parameter must include desired leading spaces itself.
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. |
| hdridx | The header index value (one-based). A hdridx value of 1 modifies the first occurrence of a header named headerf. If hdridx is greater than the number of times headerf appears, a new copy of headerf is added. |
| headerv | The header value to be added, can be a non-NULL null-terminated string or an empty string. |
Return values
- The headerf argument is NULL.
- Modifying headers in the current connection state is invalid.
- Memory allocation fails.
- A network error occurs.
- The SMFIF_CHGHDRS flag was not set when the smfi_register function was called.
Example
int ret;
SMFICTX *ctx;
...
ret = smfi_chgheader(ctx, "Content-Type", 1,
"multipart/mixed;\n\tboundary=\"foobar\"");