summaryrefslogtreecommitdiff
path: root/cesar/lib/mac_lookup_table.h
blob: 52e03347026979daec3c79ba14b66bb598d4868c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
#ifndef lib_mac_lookup_table_h
#define lib_mac_lookup_table_h
/* Cesar project {{{
 *
 * Copyright (C) 2009 Spidcom
 *
 * <<<Licence>>>
 *
 * }}} */
/**
 * \file    lib/mac_lookup_table.h
 * \brief   Table to store and lookup MAC addresses and 16 bits of data.
 * \ingroup lib
 *
 * This module handles a generic table of MAC addresses (stored on 48 bits)
 * with some extra informations stored on 16 bits. You are free to organise
 * the extra information field the way you want (i.e.: a TEI and a tag, an
 * expiration date).
 *
 * The table is provided in two formats:
 *  - the "non-sorted" format, which is suitable for editing (i.e.: adding
 *  values, updating), reading. It is not sorted. No search is possible with
 *  this table,
 *  - the "indexed" format which sorts the table based on the MAC address
 *  field. It is suitable for searching. But the table can not be edited
 *  anymore (no new entry can be added, but is possible to change the extra
 *  information associated to the MAC addresses).
 *
 * For example, here is the usual way to use it the MAC lookup table: you
 * create an empty non-sorted MAC lookup table, you add new values and them
 * you convert it into an indexed table. You can now do some optimized search
 * on it. If you want to add new values to this indexed table, you need to
 * create a new empty non-sorted table, copy the old values from the indexed
 * table, add the new one you want.
 *
 * Entries with the same MAC address field are not managed by this module and
 * are, therefore, permitted.
 */

/* Forward declarations. */
typedef struct mac_lookup_block_header_t mac_lookup_block_header_t;
typedef struct mac_lookup_table_t mac_lookup_table_t;

BEGIN_DECLS

/**
 * Create an empty non-sorted MAC lookup table.
 * \return  a MAC lookup table.
 *
 * This function is used to create an empty MAC lookup table suitable for
 * editing, that can be latter converted to a indexed one. It can not be used
 * to do some search on it.
 */
mac_lookup_block_header_t *
mac_lookup_table_create (void);

/**
 * Delete a non-sorted MAC lookup table.
 * \param  table  the non-sorted MAC lookup table to delete.
 *
 * This function is quite like the mac_lookup_table_release but take a
 * non-sorted version of the MAC lookup table. It uses when you want to cancel
 * the creation of the table without need to convert it to an indexed one.
 */
void
mac_lookup_table_delete (mac_lookup_block_header_t *table);

/**
 * Add an entry to the non-sorted MAC lookup table.
 * \param  table  the non-sorted MAC lookup table in which to add the entry.
 * \param  mac_address  the MAC address of the entry to add.
 * \param  extra_info  the extra information associated with the MAC address.
 */
void
mac_lookup_table_add_entry (mac_lookup_block_header_t *table,
                            mac_t mac_address, u16 extra_info);

/**
 * Copy entries with specific extra information from an indexed table to a
 * non-sorted one.
 * \param  indexed_table  the indexed MAC lookup table.
 * \param  non_sorted_table  the non-sorted MAC lookup table.
 * \param  mask  the mask to apply to the extra information for matching only
 * part of the extra information (useful if you have stored more than one
 * information in the extra information field).
 * \param  value  the value to match against a part of the extra information.
 * \return the count of copied entries to \a non_sorted_table.
 */
uint
mac_lookup_table_copy (mac_lookup_table_t *indexed_table,
                       mac_lookup_block_header_t *non_sorted_table,
                       u16 mask, u16 value);

/**
 * Copy entries without specific extra information from an indexed table to a
 * non-sorted one.
 * \param  indexed_table  the indexed MAC lookup table.
 * \param  non_sorted_table  the non-sorted MAC lookup table.
 * \param  mask  the mask to apply to the extra information for matching only
 * part of the extra information (useful if you have stored more than one
 * information in the extra information field).
 * \param  value  the value to match against a part of the extra information.
 * \return the count of copied entries to \a non_sorted_table.
 */
uint
mac_lookup_table_copy_except (mac_lookup_table_t *indexed_table,
                              mac_lookup_block_header_t *non_sorted_table,
                              u16 mask, u16 value);

/**
 * Create an indexed MAC lookup table from a non-sorted one.
 * \param  table  a non-sorted MAC lookup table.
 * \return an indexed MAC lookup table.
 */
mac_lookup_table_t *
mac_lookup_table_convert (mac_lookup_block_header_t *table);

/**
 * Release an indexed MAC lookup table.
 * \param  table  the indexed MAC lookup table to release.
 */
void
mac_lookup_table_release (mac_lookup_table_t *table);

/**
 * Find an entry by its MAC address into the MAC lookup table.
 * \param  table  the MAC lookup table in which to search the MAC address.
 * \param  mac_address  the MAC address of the entry to lookup for.
 * \param  extra_info  a copy of the extra information associated to the MAC
 * address if found.
 * \return return status code:
 *  - false if the \p mac_address is not in \p table,
 *  - true if the \p mac_address is in the \p table.
 */
bool
mac_lookup_table_find_entry (mac_lookup_table_t *table,
                             mac_t mac_address, u16 *extra_info);

/**
 * Find and update extra information field of an entry with a specific MAC
 * address of the MAC lookup table.
 * \param  table  the MAC lookup table in which to search for the MAC address.
 * \param  mac_address  the MAC address of the entry to lookup for.
 * \param  new_value  the new value to put in the extra information field if
 * the matching entry is found.
 * \return
 *  - true if the \p mac_address is in the \p table and the \p new_value has
 *  been set,
 *  - false if the \p mac_address is not in the \p table.
 */
bool
mac_lookup_table_find_update (mac_lookup_table_t *table,
                              mac_t mac_address, u16 new_value);

/**
 * Is an entry with a specific extra information exists into the MAC lookup
 * table.
 * \param  table  the MAC lookup table in which to search the extra
 * information.
 * \param  extra_info  the extra information of the entry to lookup for.
 * \return
 *  - false if an entry with the corresponding \p extra_info is not in
 *  \p table,
 *  - true if an entry with the corresponding \p extra_info is in
 *  \p table,
 *
 * \attention This function does not do any optimized search on the table and
 * go through each entry one by one, until it reach the end or find the first
 * entry with the corresponding extra information field.
 */
bool
mac_lookup_table_extra_info_exist (mac_lookup_table_t *table, u16 extra_info);

/**
 * Get MAC address at a desired position of a MAC lookup table.
 * \param  table  the indexed MAC lookup table.
 * \param  position  the position to get.
 * \return  the MAC address located at \a position.
 */
mac_t
mac_lookup_get_mac (mac_lookup_table_t *table, uint position);

/**
 * Get the count of entries in the MAC lookup table.
 * \param  table  the MAC lookup table.
 * \return the count of entries in the \p table.
 */
uint
mac_lookup_entry_count (mac_lookup_table_t *table);

END_DECLS

#endif /* lib_mac_lookup_table_h */