![]() |
![]() |
![]() |
MAFW Reference Manual | ![]() |
---|---|---|---|---|
enum MafwFilterType; MafwFilter; #define MAFW_FILTER_IS_COMPLEX (f) #define MAFW_FILTER_IS_SIMPLE (f) #define MAFW_FILTER_IS_VALID (f) #define MAFW_FILTER_AND (...) #define MAFW_FILTER_APPROX (k, v) #define MAFW_FILTER_EQ (k, v) #define MAFW_FILTER_EXISTS (k) #define MAFW_FILTER_GT (k, v) #define MAFW_FILTER_LT (k, v) #define MAFW_FILTER_NOT (...) #define MAFW_FILTER_OR (...) #define mafw_filter_add_children (f, ...) MafwFilter* mafw_filter_add_children_n (MafwFilter *filter, ...); void mafw_filter_free (MafwFilter *filter); MafwFilter* mafw_filter_new (MafwFilterType type, ...); MafwFilter* mafw_filter_parse (char const *filter); gchar* mafw_filter_to_string (const MafwFilter *filter); MafwFilter* mafw_filter_copy (const MafwFilter *filter); char* mafw_filter_quote (char const *str); char* mafw_filter_unquote (char const *str); charconst * mafw_filter_unquote_char (char const *str, char *cp);
MafwFilter is a tree of filter expressions, used by sources to
parse the filter
argument in mafw_source_browse()
. It can be
either built by parsing a string by mafw_filter_parse()
, or
constructed programmatically with mafw_filter_new()
or the
appropriate convenience macros.
Filter strings
The string representation of a filter is a slightly modified variant of the LDAP search string described in RFC 4515. Modifications are:
`>=' and `<=' are replaced with `>' and `<' (only one character), and they mean GREATER THAN and LESS THAN.
`~=' is replaced with `~' for approximate matching.
the `exists' operator (`=*') is represented by `?'.
extensible matching rules are not supported.
LDAPv3 escaping of `(', `)', `*' is used: they are substituted \XX,
where XX is a 2-digit hexadecimal number. See the
mafw_filter_quote()
and mafw_filter_unquote()
functions.
Attributes may consist of characters from [_-a-zA-Z0-9].
Example
`(&(artist=belga)(year>2000))' -- matches artist named `belga' with `year' after 2000.
Programmatic construction of the same filter looks like this:
MAFW_FILTER_AND(MAFW_FILTER_EQ("artist", "belga"), MAFW_FILTER_GT("year", "2000"))
typedef enum { MAFW_F_INVALID = 0, /* Aggregates. */ mafw_f_and, mafw_f_or, mafw_f_not, /* Divider between aggregate and simple filters. */ MAFW_F_COMPLEX, /* Simple ones. */ mafw_f_exists, mafw_f_eq, mafw_f_lt, mafw_f_gt, mafw_f_approx, /* last element */ MAFW_F_LAST, } MafwFilterType;
Represents the different kinds of filters used in MAFW.
typedef struct { MafwFilterType type; union { struct MafwFilter **parts; struct { char *key; char *value; }; }; } MafwFilter;
Programmatic representation of a filter.
MafwFilterType type ; |
the type of the filter (enum filter_type). |
struct MafwFilter **parts ; |
if the filter is aggregate; it's an array of pointers to
child filter structures, terminated by NULL .
|
char *key ; |
if the filter is simple; the attribute to match. |
char *value ; |
if the filter is simple; the value to match with. If the type is mafw_f_exists, it is an empty string. |
#define MAFW_FILTER_IS_COMPLEX(f)
Checks if a filter is complex
f : |
a filter instance. |
#define MAFW_FILTER_IS_SIMPLE(f)
Checks if a filter is simple
f : |
a filter instance. |
#define MAFW_FILTER_IS_VALID(f)
Checks if a filter is valid
f : |
a filter instance. |
#define MAFW_FILTER_AND(...)
Constructs a filter representing the conjunction of its arguments.
... : |
list of elements |
#define MAFW_FILTER_APPROX(k, v) mafw_filter_new(mafw_f_approx, k, v)
Constructs a filter representing `value of k
approximately matches v
'.
k : |
metadata key. |
v : |
the value. |
#define MAFW_FILTER_EQ(k, v) mafw_filter_new(mafw_f_eq, k, v)
Constructs a filter representing `value of k
equals to v
'.
k : |
metadata key. |
v : |
the value. |
#define MAFW_FILTER_EXISTS(k) mafw_filter_new(mafw_f_exists, k, NULL)
Constructs a filter representing `k
is not empty'.
k : |
metadata key. |
#define MAFW_FILTER_GT(k, v) mafw_filter_new(mafw_f_gt, k, v)
Constructs a filter representing `value of k
is greater than v
'.
k : |
metadata key. |
v : |
the value. |
#define MAFW_FILTER_LT(k, v) mafw_filter_new(mafw_f_lt, k, v)
Constructs a filter representing `value of k
is less than v
'.
k : |
metadata key. |
v : |
the value. |
#define MAFW_FILTER_NOT(...) mafw_filter_new(mafw_f_not, ##__VA_ARGS__, NULL)
Constructs a filter representing negation of its argument.
... : |
list of elements |
#define MAFW_FILTER_OR(...) mafw_filter_new(mafw_f_or, ##__VA_ARGS__, NULL)
Constructs a filter representing disjunction of its arguments.
... : |
list of elements |
#define mafw_filter_add_children(f, ...)
Adds children nodes to the given filter. Does nothing if the
filter is not an aggregate filter (AND, OR). Use the
mafw_filter_add_children()
convenience macro that adds the
terminating NULL
automatically.
f : |
the filter to add to. |
... : |
list of children |
MafwFilter* mafw_filter_add_children_n (MafwFilter *filter, ...);
Adds children nodes to the given filter. Does nothing if the
filter is not an aggregate filter (AND, OR). Use the
mafw_filter_add_children()
convenience macro that adds the
terminating NULL
automatically.
filter : |
the filter to add to. |
... : |
a NULL terminated list of "s" to add.
|
Returns : | the modified filter. |
void mafw_filter_free (MafwFilter *filter);
Frees a filter tree recursively. Does nothing if NULL
is passed.
filter : |
the filter tree to free. |
MafwFilter* mafw_filter_new (MafwFilterType type, ...);
Creates a new filter tree node.
type : |
the type of the filter (MafwFilterType). |
... : |
depending on the type, either a NULL terminated list of
"s", or if it's a simple type, a key and a value.
In the second case, the key and value pointers are duplicated.
|
Returns : | the newly allocated filter node. |
MafwFilter* mafw_filter_parse (char const *filter);
Builds a filter tree from the given filter
expression.
filter : |
the string representation of a MAFW filter. |
Returns : | a newly allocated filter tree, or NULL if the string contains
syntax errors.
|
gchar* mafw_filter_to_string (const MafwFilter *filter);
Transforms the MafwFilter into a string representation. If you created that MafwFilter from a string representation, the result of calling this function doesn't have to return the same string, just the an equivalent one.
filter : |
a MafwFilter |
Returns : | a newly allocated string, or NULL if the filter was NULL
or incorrect
|
MafwFilter* mafw_filter_copy (const MafwFilter *filter);
Copies a MafwFilter
filter : |
a MafwFilter |
Returns : | a newly allocated MafwFilter, or NULL if any error
occurs
|
char* mafw_filter_quote (char const *str);
Quotes str
according to LDAPv3 rules. The following characters
are quoted: '*', '(', ')', '\'.
str : |
the string to quote. |
Returns : | a newly allocated quoted string. |
char* mafw_filter_unquote (char const *str);
Unquotes the LDAPv3 quoted string str
.
str : |
a LDAPv3 quoted string. |
Returns : | a newly allocated string containing the unquoted value of str
or NULL if str is quoted improperly
|
charconst * mafw_filter_unquote_char (char const *str, char *cp);
Unquotes one token (a character or an escape sequence) of str
.
The token must not be an unquoted NIL, so you need to check the
end-of-string condition prior to calling this function. This is
because the return value would point out of bounds or be ambiguous
otherwise. This function is intended for sources that need to
unescape then reescape in a domain-specific format property values.
str : |
points to the token to unquote |
cp : |
points to the char to store the unquoted value |
Returns : | the starting position of the next token or NULL
if the current token was found to be ununquotable.
|