.\"Copyright 2008-2010 IBM Corp.
.TH SCI_Filter_load 3 "Dec 4, 2009" "1.0.0" "SCI"

.SH NAME
\fBSCI_Filter_load\fP \- Load a new message filter

.SH SYNTAX
.ft R

.SH C Syntax
.nf
#include <sci.h>
int SCI_Filter_load(sci_filter_info_t *\fIfilter_info\fP)

.SH INPUT PARAMETERS
.ft R
.TP 1i
filter_info
The information of the filter to be loaded (IN).

.SH DESCRIPTION
.ft R
This subroutine is used to load a new message with id specifed by \fIfilter_id\fP,
if success, the initialization handler defined in the filter will be called.
.sp
In \fIsci_filter_info_t\fP:
.sp
.nf
        typedef struct {
                int              filter_id;
                char             *so_file;
        } sci_filter_info_t;
.fi
.sp
\fIfilter_id\fP indicates the id of the new filter, and \fIfilter_id\fP can be any positive
integers. \fIso_file\fP indicates the absolute path of the filter library.
.sp
In SCI, a message filter is specified by a shared library, in this shared library,
at least the following three functions (name fixed) should be defined:
.sp
.nf
        // initialization handler
        int filter_initialize(void **user_param);
        // termination handler
        int filter_terminate(void *user_param);
        // message handler
        int filter_input(void *user_param, sci_group_t group, void *buf, int size);
.fi
.sp
The user-defined function \fBfilter_input\fP will be called each time when a new
message is arrived. The \fIfilter_id\fP can be used for \fBSCI_Bcast\fP, \fBSCI_Upload\fP
or \fBSCI_Filter_upload\fP once the filter has been loaded successfully.
.sp
For more information, please refer to SCI's online documents.

.SH EXAMPLE
.ft R
.nf
        int filter_initialize(void **user_param)
        {
                ...
                return SCI_SUCCESS;
        }

        int filter_terminate(void *user_param) 
        {
                ...
                return SCI_SUCCESS;
        }

        int filter_input(void *user_param, sci_group_t group, void *buf, int size) 
        {
                void *bufs[1];
                int sizes[1];
                int rc;
        
                bufs[0] = buf;
                sizes[0] = size;
    
                rc = SCI_Filter_upload(SCI_FILTER_NULL, group, 1, bufs, sizes);
                if (rc != SCI_SUCCESS) {
                        ...
                } 
    
                return SCI_SUCCESS;
        }

        {
                sci_filter_info_t filter_info;
                filter_info.filter_id = 1;
                filter_info.so_file = "/usr/lib/myfilter.so";
                SCI_Filter_load(&filter_info);
        }
.fi

.SH ERRORS
.ft R
All SCI routines return an error value.
.sp
.TP 1i
SCI_ERR_UNINTIALIZED
Uninitialized SCI execution environment
.TP 1i
SCI_ERR_INVALID_CALLER
Can only be called in the front end
.TP 1i
SCI_ERR_FILTER_PREDEFINED
Can't load predefined filter SCI_FILTER_NULL
.TP 1i
SCI_ERR_FILTER_ID
Can't set negative \fIfilter_id\fP
.TP 1i
SCI_ERR_NO_MEM
Out of memory

.SH SEE ALSO
.ft R
.nf
\fBSCI_Filter_unload\fP(3)