NAME    [Toc]    [Back]

       EvmFilterCreate, EvmFilterSet, EvmFilterTest, EvmFilterIsFile,
 EvmFilterReadFile, EvmFilterDestroy -  Event  filter
       evaluator routines

SYNOPSIS    [Toc]    [Back]

       #include <evm/evm.h>

       EvmStatus_t EvmFilterCreate(
               EvmFilter_t  *filter_evaluator ); EvmStatus_t EvmFilterSet(

               EvmFilter_t filter_evaluator,
               const  EvmString_t  filter_string  );  EvmStatus_t
       EvmFilterTest(
               EvmFilter_t filter_evaluator,
               EvmEvent_t event,
               EvmBoolean_t *matchFlag ); EvmBoolean_t EvmFilterIsFile(

               const char *filter_string ); char * EvmFilterReadFile(

               const  char  *filter_string ); EvmStatus_t EvmFilterDestroy(

               EvmFilter_t filter_evaluator );

OPERANDS    [Toc]    [Back]

       For EvmFilterCreate() this is the  return  handle  of  the
       instance of a filter evaluator established.

              For EvmFilterSet() this identifies the filter evaluator
 that will use the filter_string in subsequent
              matches.

              For  EvmFilterTest()  this  identifies  the  filter
              evaluator that will compare the supplied event with
              the filter string.

              For  EvmFilterDestroy()  this identifies the filter
              evaluator to be destroyed.  The filter string to be
              used by the filter evaluator in subsequent matches.
              See the EvmFilter(5) reference page for the syntax.
              The  event  to  be  compared with the filter string
              currently associated  with  the  filter  evaluator.
              The result obtained when the supplied event is compared
 with the filter string  currently  associated
              with  the  filter evaluator. Possible return values
              are  as  follows:  The  event  matches   the   filter_string.
   The  event  does  not  match the filter_string.

DESCRIPTION    [Toc]    [Back]

       The filter evaluation routines are used to  check  whether
       an  event  matches a given event filter. Although most EVM
       clients do not need to use these functions directly,  they
       are  useful  to  clients that pass a complex filter to the
       EVM daemon, and then test incoming events against  subcomponents
 of the filter to determine the appropriate action.

       The EvmFilterCreate() routine establishes an instance of a
       filter  evaluator, returning a handle in filter_evaluator.

       The EvmFilterSet() routine passes a filter_string  to  the
       filter_evaluator to be used in subsequent matches.

       The  EvmFilterTest()  routine  compares the supplied event
       with the filter_string currently associated with the  filter_evaluator.
 The result is returned in matchFlag. Possible
 return values are as follows: The  event  matches  the
       filter_string.    The   event  does  not  match  the  filter_string.


       The indirect filter syntax, @filename, is supported by the
       EvmFilterIsFile()  and  EvmFilterReadFile() routines. Programs
 which support indirect filters may use  EvmFilterIsFile()
  to determine whether a user-supplied filter string
       is indirect, and, if so, can then use  EvmFilterReadFile()
       to expand the file to a regular filter string.

       EvmFilterIsFile()  returns  EvmTRUE  if  the supplied filter_string
 uses indirect  filter  notation,  and  EvmFALSE
       otherwise.

       EvmFilterReadFile() interprets the supplied filter_string,
       and attempts to open and read the referenced file, returning
 a pointer to heap space memory containing the expanded
       filter string. The caller is responsible for  freeing  the
       memory  when  it is no longer needed.  NULL is returned if
       an error was encountered while reading the file. Note that
       EvmFilterReadFile()  does not attempt to validate the filter
 string contained in the file.

       The EvmFilterDestroy() routine destroys the filter_evaluator,
 freeing all associated resources.

RESTRICTIONS    [Toc]    [Back]

       None

RETURN VALUES    [Toc]    [Back]

       The  operation  was  completed  without  error.   A filter
       string passed to the filter  evaluator  was  syntactically
       invalid.   One  of  the  arguments  to  the  function  was
       invalid.  A value in a structure member  is  invalid.   An
       operation failed because an attempt to acquire heap memory
       failed.  An attempt was made to  use  a  filter  evaluator
       without first calling EvmFilterSet() to provide an initial
       filter string.  A filter string passed to the filter evaluator
  was  syntactically  invalid.   An attempt to read a
       filter file failed.

ERRORS    [Toc]    [Back]

       None

LIBRARY    [Toc]    [Back]

       EVM Support Library (libevm.so, libevm.a)

FILES    [Toc]    [Back]

       None

SEE ALSO    [Toc]    [Back]

       Files: kevm(7)

       Event Management: EVM(5)

       EVM Events: EvmEvent(5)

       Event Filter: EvmFilter(5)



                                               EvmFilterCreate(3)