| .\"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) |
