NAME

cat_pushfilter - Push a filter onto the filter stack

SYNOPSIS

#include <cat.h>

int cat_pushfilter(cat_session *session, const cat_filter *filter);

DESCRIPTION

A filter is defined as:

 struct cat_filter {
        char name[CAT_MAX_FILTERNAME];
        int fd_ids;
        int (*init)(cat_session *session, cat_filter *filter);
        int (*rw)(cat_session *session, cat_filter *filter, int fd);
        void (*free)(cat_session *session, cat_filter *filter);
        void *filterdata;
 };

This function pushes filter onto the filter stack, affecting reads and/or writes when communicating with the client or server. The fields from the supplied cat_filter struct will be copied into internal data structures. When the filter is installed, its init function is called.

The rw function is called for every data packet that passes through the session on the fd_ids for which the filter is registered. The function can insert, delete, or modify any data, as it considers necessary. The data is extracted from the stack using catbuf_get(), and is re-inserted using catbuf_put().

The rw function should return 0 during normal operation. The following return codes from a filter rw function are handled in a special way:

CAT_EOF
Close the connection after this packet has been delivered.

CAT_UNMANAGE
Remove the session from catsock_run().

CAT_CONTINUE, CAT_EAGAIN
Synonymous with CAT_OK (0).

CAT_POP_FILTER
Pop this filter.

CAT_MORE_DATA
The filter has more data, which it will deliver in the next call to cat_recv().

If a filter registers itself with the flag CAT_CLOSED, in addition to any file descriptors, the filter will also be called when the connection has been closed (with the CAT_CLOSED flag set together with the fd where the event occurred). This normally terminates the session, unless the filter returns CAT_CONTINUE.

NOTES

When running in forking mode on UNIX, sessions will be closed as part of the cleanup procedure in the child process.

RETURN VALUES

The function returns the error code from the init function. The return value should be CAT_OK if successful; otherwise, a negative error code is returned.

SEE ALSO

cat, catbuf, cat_popfilter