Browse Source

* document filter api

master
Alex 'AdUser' Z 8 years ago
parent
commit
b6fe9e0646
  1. 136
      src/filters/filter.h

136
src/filters/filter.h

@ -15,18 +15,138 @@
#include "../strlcpy.h" #include "../strlcpy.h"
/**
* @file
* This header describes module API of type 'filter'
*
* Sample workflow of module usage:
*
* @msc
* f2b, filter;
* f2b => filter [label="create(id)"];
* f2b << filter [label="module handler, cfg_t *cfg"];
* |||;
* f2b => filter [label="config(cfg, param, value)"];
* f2b << filter [label="true"];
* f2b => filter [label="config(cfg, param, value)"];
* f2b << filter [label="true"];
* f2b => filter [label="config(cfg, param, value)"];
* f2b << filter [label="false"];
* f2b => filter [label="error(cfg)"];
* f2b << filter [label="const char *error"];
* --- [label="filter is ready for append()"];
* f2b => filter [label="append(cfg, pattern)"];
* f2b << filter [label="true"];
* f2b => filter [label="append(cfg, pattern)"];
* f2b << filter [label="false"];
* f2b => filter [label="error(cfg)"];
* f2b << filter [label="const char *error"];
* ||| [label="more calls of append()"];
* f2b => filter [label="ready(cfg)"];
* f2b << filter [label="true"];
* --- [label="filter is ready to use"];
* f2b => filter [label="match(cfg, line, buf, sizeof(buf))"];
* f2b << filter [label="false"];
* ... [label="no match"];
* f2b => filter [label="match(cfg, line, buf, sizeof(buf))"];
* f2b << filter [label="true"];
* ... [label="match found, buf filled with ipaddr"];
* f2b >> filter [label="stats(cfg, &matches, &pattern, true)"];
* f2b << filter [label="true"];
* f2b >> filter [label="stats(cfg, &matches, &pattern, false)"];
* f2b << filter [label="true"];
* f2b >> filter [label="stats(cfg, &matches, &pattern, false)"];
* f2b << filter [label="false"];
* ... [label="no more stats"];
* f2b => filter [label="flush(cfg)"];
* f2b << filter [label="true"];
* --- [label="now you may config(), append() or destroy() filter"];
* f2b => filter [label="destroy(cfg)"];
* @endmsc
*/
/**
* @def ID_MAX
* Maximum length of name for usage in @a start()
*/
#define ID_MAX 32 #define ID_MAX 32
/**
* @def PATTERN_MAX
* Maximum length of regex
*/
#define PATTERN_MAX 256 #define PATTERN_MAX 256
/**
* @def HOST_TOKEN
* Use this string in place where to search for ip address
*/
#define HOST_TOKEN "<HOST>" #define HOST_TOKEN "<HOST>"
/**
* Opaque module handler, contains module internal structs
*/
typedef struct _config cfg_t; typedef struct _config cfg_t;
/**
* @brief Create instance of module
* @param id Module name string
* @returns Opaque module handler or NULL on failure
*/
extern cfg_t *create(const char *id); extern cfg_t *create(const char *id);
extern const char *error(cfg_t *c); /**
extern bool config(cfg_t *c, const char *key, const char *value); * @brief Returns last error description
extern bool append(cfg_t *c, const char *pattern); * @param cfg Module handler
extern bool ready(cfg_t *c); * @returns Pointer to string with description of last error
extern bool stats(cfg_t *c, int *matches, char **pattern, bool reset); * @note Returned pointer not marked with const, because libdl complains,
extern bool match(cfg_t *c, const char *line, char *buf, size_t bufsize); * but contents on pointer should not be modified or written in any way
extern void flush(cfg_t *c); */
extern void destroy(cfg_t *c); extern const char *error(cfg_t *cfg);
/**
* @brief Contigure module instance
* @param cfg Module handler
* @param key Parameter name
* @param value Parameter value
* @returns true on success, false on error with setting intenal error buffer
*/
extern bool config(cfg_t *cfg, const char *key, const char *value);
/**
* @brief Add match pattern
* @param cfg Module handler
* @param pattern Regex expression
* @returns true on success, false on error with setting intenal error buffer
*/
extern bool append(cfg_t *cfg, const char *pattern);
/**
* @brief Checks is module ready for usage
* @param cfg Module handler
* @returns true if ready, false if not
*/
extern bool ready(cfg_t *cfg);
/**
* @brief Fetch match stats by-pattern
* @param cfg Module handler
* @param matches Pointer to storage for matches count
* @param pattern Associated pattern
* @param reset Reset to start of statistics (for later calls)
* @returns false on no more stats or true otherwise with filling @a matches and @a pattern
*/
extern bool stats(cfg_t *cfg, int *matches, char **pattern, bool reset);
/**
* @brief Match given line against configured regexps
* @param cfg Module handler
* @param line Source line of data
* @param buf Buffer for storing match result
* @param bufsize Size of buffer above
* @returns false if no match or true otherwise with filling @a buf
*/
extern bool match(cfg_t *cfg, const char *line, char *buf, size_t bufsize);
/**
* @brief Destroy all added patterns and free it's resources
* @param cfg Module handler
*/
extern void flush(cfg_t *cfg);
/**
* @brief Free module handle
* @param cfg Module handler
* @note Module handler becomes invalid after calling this function on it
*/
extern void destroy(cfg_t *cfg);

Loading…
Cancel
Save