# smfi_register

SYNOPSIS

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

Register a set of filter callbacks.

DESCRIPTION

Called When | smfi_register must be called before smfi_main
Effects | smfi_register creates a filter using the information given in the smfiDesc argument. Multiple (successful) calls to smfi_register within a single process are not allowed, i.e., only one filter can be successfully registered. Note, however, that the library may not check whether this restriction is obeyed.

ARGUMENTS

Argument | Description
--- | ---

descr

A filter descriptor of type smfiDesc describing the filter's 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 wish to process the given type of information, simply returning SMFIS_CONTINUE.

RETURN VALUES

smfi_register may return MI_FAILURE for any of the following reasons:

- memory allocation failed.
- incompatible version or illegal flags value.

NOTES

The xxfi_flags field should contain the bitwise OR of zero or more of the following values, describing the actions the filter may take:

Flag | Description
--- | ---
SMFIF_ADDHDRS | This filter may add headers.
SMFIF_CHGHDRS | This filter may change and/or delete headers.
SMFIF_CHGBODY | This filter may replace the body during filtering. This may have significant performance impact if other filters do body filtering after this filter.
SMFIF_ADDRCPT | This filter may add recipients to the message.
SMFIF_ADDRCPT_PAR | This filter may add recipients including ESMTP args.
SMFIF_DELRCPT | This filter may remove recipients from the message.
SMFIF_QUARANTINE | This filter may quarantine a message.
SMFIF_CHGFROM | This filter may change the envelope sender (MAIL).
SMFIF_SETSYMLIST | This filter can send a set of symbols (macros) that it wants.

Copyright (c) 2000-2001, 2003, 2006 Sendmail, Inc. and its suppliers. All rights reserved.
By using this file, you agree to the terms and conditions set forth in the LICENSE.