smfi_register Function

Edit online

Purpose

The smfi_register function registers a set of sendmail filter callback functions.

Syntax

#include <libmilter/mfapi.h>
int smfi_register(
smfiDesc descr)
);

Description

The smfi_register function creates a sendmail filter by using the information provided in the smfiDesc argument. The smfi_register function must be called before smfi_main function.
Note: Multiple successful calls to smfi_register function within a single process are not allowed. Only a single sendmail filter can be successfully registered. Note, however, that the library cannot check if the restriction is obeyed.

The xxfi_flags field must contain the bitwise or zero or any of the following values, describing the actions the sendmail filter can take.

Table 1. Values
Item Description
SMFIF_ADDHDRS The smfi_addheader function adds headers.
SMFIF_CHGHDRS The smfi_chgheader function either modifies headers or deletes headers.
SMFIF_CHGBODY The smfi_replacebody function replaces the body during filtering. The filter has significant performance impact if other filters do body filtering after this filter.
SMFIF_ADDRCPT The smfi_addrcpt function adds recipients to the message.
SMFIF_ADDRCPT_PAR The smfi_addrcpt_par function adds recipients including extended simple mail transfer protocol (ESMTP) arguments.
SMFIF_DELRCPT The smfi_delrcpt function removes recipients from the message.
SMFIF_QUARANTINE The smfi_quarantine function quarantines a message.
SMFIF_CHGFROM The smfi_chgfrom function modifies the envelope sender (Mail From).
SMFIF_SETSYMLIST The smfi_setsymlist function sends a set of symbols (macros) that are required.

Arguments

Table 2. Arguments
Item Description
descr A filter descriptor of type smfiDesc describing the filters functions. The structure has the following members: 
struct smfiDesc
{
	char		*xxfi_name;	/* filter name */
	int		xxfi_version;	/* version code 
-- do not change */
	unsigned long	xxfi_flags;	/* flags */

	/* connection info filter */
	sfsistat	(*xxfi_connect)(SMFICTX *, 
char 
*, _SOCK_ADDR *);
	/* SMTP HELO command filter */
	sfsistat	(*xxfi_helo)(SMFICTX *, 
char *);
	/* envelope sender filter */
	sfsistat	(*xxfi_envfrom)(SMFICTX *, 
char **);
	/* envelope recipient filter */
	sfsistat	(*xxfi_envrcpt)(SMFICTX *, 
char **);
	/* header filter */
	sfsistat	(*xxfi_header)(SMFICTX *, 
char *,
 char *);
	/* end of header */
	sfsistat	(*xxfi_eoh)(SMFICTX *);
	/* body block */
	sfsistat	(*xxfi_body)(SMFICTX *, 
unsigned char 
*, size_t);
	/* end of message */
	sfsistat	(*xxfi_eom)(SMFICTX *);
	/* message aborted */
	sfsistat	(*xxfi_abort)(SMFICTX *);
	/* connection cleanup */
	sfsistat	(*xxfi_close)(SMFICTX *);

	/* any unrecognized or unimplemented 
command filter */
	sfsistat	(*xxfi_unknown)(SMFICTX 
*, const char *);

	/* SMTP DATA command filter */
	sfsistat	(*xxfi_data)(SMFICTX *);

	/* negotiation callback */
	sfsistat (*xxfi_negotiate)(SMFICTX *,
		unsigned long, unsigned long, 
unsigned long,
 unsigned long,
		unsigned long *, unsigned long *, 
unsigned long *, 
unsigned long *
);
};

A NULL value for any callback function indicates that the filter does not process the given type of information, and returns SMFIS_CONTINUE.
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_register function returns the MI_FAILURE value in the following cases. Otherwise, the function returns MI_SUCCESS.
  • Memory allocation failed.
  • Incompatible version or illegal flags value.

Related information

libmilter_smfi_addheader.html

libmilter_smfi_chgheader.html

libmilter_smfi_replacebody.html

libmilter_smfi_addrcpt.html

libmilter_smfi_addrcpt_par.html

libmilter_smfi_delrcpt.html

libmilter_smfi_quarantine.html

libmilter_smfi_chgfrom.html

libmilter_smfi_setsymlist.html