#ifndef lib_mac_lookup_table_h #define lib_mac_lookup_table_h /* Cesar project {{{ * * Copyright (C) 2009 Spidcom * * <<>> * * }}} */ /** * \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 */