Operations on Rulesets

Collaboration diagram for Operations on Rulesets:

Enumerations
enum	changerules_what { do_add , do_del }
	Whether to add or delete rules in the ruleset.

Functions
static bool	rules_dbnext (const MDB_val *dbdata, char **rule)
	Next in iteration over a ruleset, started with rules_dbloop(). More...
static bool	rules_dbloop (const MDB_val *dbdata, char **rule)
	Start iteration over a ruleset, continue with rules_dbnext(). More...
static bool	rules_dbcutnext (MDB_val *dbdata, char **rule, bool cutrule)
	While iterating over a ruleset, possible remove the current rule before focussing on the next rule. This function iterates to the next rule in a ruleset, but when cutrule is set it first removes the current rule from the ruleset. This allows filtering content for further processing. More...
bool	rules_dbget (struct rules_db *ruledb, rules_dbkey digkey, MDB_val *out_dbdata)
	Get rules from the RuleDB. More...
bool	rules_edit_generic (rules_dbkey svckey, unsigned svckeylen, char *xsname, char *rules, unsigned ruleslen, changerules_what whattodo, a2sel_t *opt_selector, struct rules_db *opt_nested)
static bool	rules_dbadd (rules_dbkey prekey, unsigned prekeylen, char *xskey, char *rules, unsigned ruleslen, a2sel_t *opt_selector)
	Add rules to the database. More...
static bool	rules_dbdel (rules_dbkey prekey, unsigned prekeylen, char *xskey, char *rules, unsigned ruleslen, a2sel_t *opt_selector)
	Delete rules from the database. More...
bool	rules_dbset (struct rules_db *ruledb, MDB_val *in0_dbdata, MDB_val *in1_dbdata)
	Set rules in the RuleDB. More...

Detailed Description

Function Documentation

rules_dbadd()

static bool rules_dbadd ( rules_dbkey  prekey, unsigned  prekeylen, char *  xskey, char *  rules, unsigned  ruleslen, a2sel_t *  opt_selector  )

inlinestatic

Add rules to the database.

Given a prepared key encompssing the Access Domain and Type, create records for the given Access Name and Rule. The records should represent the ruleset provided as concatenated NUL-terminated strings. When opt_selector is provided, the changes will be made specifically for that Selector; otherwise, "~selector" words may specify one or more Selector to update.

This function returns true on success only. This success is the result of a commit on the underlying database, so it ought to be true for all the records that a rule may generate.

rules_dbcutnext()

static bool rules_dbcutnext ( MDB_val *  dbdata, char **  rule, bool  cutrule  )

inlinestatic

While iterating over a ruleset, possible remove the current rule before focussing on the next rule. This function iterates to the next rule in a ruleset, but when cutrule is set it first removes the current rule from the ruleset. This allows filtering content for further processing.

rules_dbcutnext

LMDB does not support this direct access to its memory. You need to clone data retrieved from LMDB before using it with rules_dbcutnext().

Parameters

cutrule

True to cut the current rule or false to leave it

See also

rules_dbloop

rules_dbnext

Returns

true if a new Rule was setup

rules_dbdel()

static bool rules_dbdel ( rules_dbkey  prekey, unsigned  prekeylen, char *  xskey, char *  rules, unsigned  ruleslen, a2sel_t *  opt_selector  )

inlinestatic

Delete rules from the database.

Given a prepared key encompssing the Access Domain and Type, delete records for the given Access Name and Rule. The records should represent the ruleset provided as concatenated NUL-terminated strings. When opt_selector is provided, the changes will be made specifically for that Selector; otherwise, "~selector" words may specify one or more Selector to update.

This function returns true on success only. This success is the result of a commit on the underlying database, so it ought to be true for all the records that a rule may generate.

rules_dbget()

bool rules_dbget	(	struct rules_db *	ruledb,
		rules_dbkey	digkey,
		MDB_val *	out_dbdata
	)

Get rules from the RuleDB.

Every rule is terminated by a NUL character and the functions rules_dbloop() and _dbnext() can be used as iterators to pass through them.

This function returns true on success. This includes when it finds no record, for which it returns an empty set of rules.

The digest key will be split into the LMDBkey and RESTkey. Cursor iteration is used to search for a record to allow just that.

Note that what the database considers a value is not yet a value to the application. The first RULES_TRUNK_SIZE bytes hold the trunk identifier, then comes the RESTkey and only then does application data start. This application data holds a Ruleset in the case of the RuleDB; this is also called an Access Control List in some cases. This call returns only the application data.

rules_dbloop()

static bool rules_dbloop ( const MDB_val *  dbdata, char **  rule  )

inlinestatic

Start iteration over a ruleset, continue with rules_dbnext().

rules_dbloop

See also

rules_dbnext

rules_dbcutnext

Returns

true if a Rule was found

rules_dbnext()

static bool rules_dbnext ( const MDB_val *  dbdata, char **  rule  )

inlinestatic

Next in iteration over a ruleset, started with rules_dbloop().

rules_dbnext

See also

rules_dbloop

rules_dbcutnext

Returns

true if a Rule was found

Iterate over an MDB_val with a sequence of NUL-terminated rules, as returned by rules_dbget(). The normal construction is

... rules_dbget (..., &dbdata);
char *rule;
if (rules_dbloop (&dbdata, &rule)) do {
   ...process (rule)...
} while (rules_dbnext (&dbdata, &rule));

rules_dbset()

bool rules_dbset	(	struct rules_db *	ruledb,
		MDB_val *	in0_dbdata,
		MDB_val *	in1_dbdata
	)

Set rules in the RuleDB.

The rules must be NUL terminated but more than one of them can be combined in the inputs. The two offered bits are concatenated to simplify updates. Even more friendly use is possible with the wrappers rules_dbadd() and _dbdel().

This function operates on the assumption that rules_dbget() was run before, and returned successfully. This is why no digest key is required. The input data is allowed to point into data that was acquired during that call.

To add rules with this function, set in0_dbdata to the result of rules_dbget() and set in1_dbdata to the new rules, each with a NUL terminator. Or switch the two to insert at the beginning.

To delete rules with this function, set in0_dbdata to the part of rules_dbget() before the rule that will be removed, in1_dbdata to the part after the rule to be removed (making sure to also remove its trailing NUL character). Either or both of these may be empty.

This function returns true on succes.

Note that what the database considers a value is not yet a value to the application. The first RULES_TRUNK_SIZE bytes hold the trunk identifier, then comes the RESTkey and only then does application data start. This application data holds a Ruleset in the case of the RuleDB; this is also called an Access Control List in some cases. This call expects to be handed only application data.