summaryrefslogtreecommitdiff
path: root/cesar/lib/mac_lookup_table.h
diff options
context:
space:
mode:
authordufour2009-10-05 14:29:14 +0000
committerdufour2009-10-05 14:29:14 +0000
commit8b4924d23ee8d51e78462ad00073a0ba3eee39af (patch)
treefff191c8a00ce16dce183ae0f711384cb24541dd /cesar/lib/mac_lookup_table.h
parentf5cbc43d3419049028ca53eeb9a5231cd0e1920d (diff)
cesar/{cl,lib}: move cl/mac_lookup_table to lib directory (closes #606)
Move mac_lookup_table module from the cl to the lib directory. Also correct a minor indentation problem. git-svn-id: svn+ssh://pessac/svn/cesar/trunk@5921 017c9cb6-072f-447c-8318-d5b54f68fe89
Diffstat (limited to 'cesar/lib/mac_lookup_table.h')
-rw-r--r--cesar/lib/mac_lookup_table.h193
1 files changed, 193 insertions, 0 deletions
diff --git a/cesar/lib/mac_lookup_table.h b/cesar/lib/mac_lookup_table.h
new file mode 100644
index 0000000000..52e0334702
--- /dev/null
+++ b/cesar/lib/mac_lookup_table.h
@@ -0,0 +1,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 */