EvmFilterCreate(3)EvmFilterCreate(3)NAME
EvmFilterCreate, EvmFilterSet, EvmFilterTest, EvmFilterIsFile, EvmFil‐
terReadFile, EvmFilterDestroy - Event filter evaluator routines
SYNOPSIS
#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
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 evalu‐
ator 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 fil‐
ter_string. The event does not match the filter_string.
DESCRIPTION
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 eval‐
uator, returning a handle in filter_evaluator.
The EvmFilterSet() routine passes a filter_string to the filter_evalua‐
tor to be used in subsequent matches.
The EvmFilterTest() routine compares the supplied event with the fil‐
ter_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 fil‐
ter_string.
The indirect filter syntax, @filename, is supported by the EvmFilterIs‐
File() and EvmFilterReadFile() routines. Programs which support indi‐
rect filters may use EvmFilterIsFile() to determine whether a user-sup‐
plied filter string is indirect, and, if so, can then use EvmFilter‐
ReadFile() 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 EvmFil‐
terReadFile() does not attempt to validate the filter string contained
in the file.
The EvmFilterDestroy() routine destroys the filter_evaluator, freeing
all associated resources.
RESTRICTIONS
None
RETURN VALUES
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
None
LIBRARY
EVM Support Library (libevm.so, libevm.a)
FILES
None
SEE ALSO
Files: kevm(7)
Event Management: EVM(5)
EVM Events: EvmEvent(5)
Event Filter: EvmFilter(5)EvmFilterCreate(3)