Contiki 2.6

neighbor-attr.h

00001 /*
00002  * Copyright (c) 2010, Vrije Universiteit Brussel
00003  * All rights reserved.
00004  *
00005  * Redistribution and use in source and binary forms, with or without
00006  * modification, are permitted provided that the following conditions
00007  * are met:
00008  * 1. Redistributions of source code must retain the above copyright
00009  *    notice, this list of conditions and the following disclaimer.
00010  * 2. Redistributions in binary form must reproduce the above copyright
00011  *    notice, this list of conditions and the following disclaimer in the
00012  *    documentation and/or other materials provided with the distribution.
00013  * 3. Neither the name of the Institute nor the names of its contributors
00014  *    may be used to endorse or promote products derived from this software
00015  *    without specific prior written permission.
00016  *
00017  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
00018  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00019  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00020  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
00021  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00022  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00023  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00024  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00025  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
00026  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00027  * SUCH DAMAGE.
00028  *
00029  *
00030  * Author: Joris Borms <joris.borms@vub.ac.be>
00031  *
00032  */
00033 #ifndef NEIGHBORATTR_H_
00034 #define NEIGHBORATTR_H_
00035 
00036 #include "net/rime.h"
00037 
00038 /**
00039  * define how many neighbors you can store
00040  */
00041 #ifdef NEIGHBOR_CONF_MAX_NEIGHBORS
00042 #define NEIGHBOR_ATTR_MAX_NEIGHBORS NEIGHBOR_CONF_MAX_NEIGHBORS
00043 #else                           /* NEIGHBOR_CONF_MAX_NEIGHBORS */
00044 #define NEIGHBOR_ATTR_MAX_NEIGHBORS 12
00045 #endif                          /* NEIGHBOR_CONF_MAX_NEIGHBORS */
00046 
00047 /**
00048  * \brief      properties of a single neighbor
00049  */
00050 struct neighbor_addr {
00051   struct neighbor_addr *next;
00052   rimeaddr_t addr;
00053   uint16_t time;
00054   uint16_t index;
00055 };
00056 
00057 /**
00058  * \brief      properties that define a neighbor attribute
00059  */
00060 struct neighbor_attr {
00061   struct neighbor_attr *next;
00062   uint16_t size;
00063   void *default_value;
00064   void *data;
00065 };
00066 
00067 /**
00068  * \brief      Define space for additional parameters in neighbor table entries.
00069  * \param type The type of the attribute.
00070  * \param name The name of the attribute.
00071  * \param def  A ptr to the default value for this attribute. If NULL, attribute will
00072  *             be filled with zeroes by default.
00073  *
00074  *             The attribute 'name' should be registered with 'neighbor_attr_register'
00075  *             during initialization.
00076  */
00077 #define NEIGHBOR_ATTRIBUTE(type, name, default_value_ptr) \
00078   static type _##name##_mem[NEIGHBOR_ATTR_MAX_NEIGHBORS]; \
00079   static struct neighbor_attr name = \
00080     {NULL, sizeof(type), default_value_ptr, (void *)_##name##_mem}
00081 
00082 /** Same as NEIGHBOR_ATTRIBUTE, only the attr is not declared static
00083  * this way you can say <tt>extern struct neighbor_attr name</tt> in header to declare
00084  * a global neighbor attribute
00085  */
00086 #define NEIGHBOR_ATTRIBUTE_GLOBAL(type, name, default_value_ptr) \
00087           static type _##name##_mem[NEIGHBOR_ATTR_MAX_NEIGHBORS]; \
00088           struct neighbor_attr name = \
00089             {NULL, sizeof(type), default_value_ptr, (void *)_##name##_mem}
00090 
00091 #define NEIGHBOR_ATTRIBUTE_DECLARE(name) extern struct neighbor_attr name
00092 
00093 /**
00094  * \brief      register a neighbor attribute
00095  * \retval     non-zero if successful, zero if not
00096  */
00097 int neighbor_attr_register(struct neighbor_attr *);
00098 
00099 /**
00100  * \retval     head of neighbor list, useful for iterating over all neighbors
00101  */
00102 struct neighbor_addr *neighbor_attr_list_neighbors(void);
00103 
00104 /**
00105  * \brief      Check if a neighbor is already added to the neighbor table
00106  * \retval     non-zero if present, zero if not
00107  */
00108 int neighbor_attr_has_neighbor(const rimeaddr_t *addr);
00109 
00110 /**
00111  * \brief      Add a neighbor entry to neighbor table
00112  * \retval     -1 if unsuccessful, 0 if the neighbor was already
00113  *             in the table, and 1 if successful
00114  */
00115 int neighbor_attr_add_neighbor(const rimeaddr_t *addr);
00116 
00117 /**
00118  * \brief      Remove a neighbor entry to neighbor table
00119  * \retval     -1 if unsuccessful, 0 if the neighbor was removed
00120  */
00121 int neighbor_attr_remove_neighbor(const rimeaddr_t *addr);
00122 
00123 /**
00124  * \brief      Get pointer to neighbor table data specified by id
00125  * \param      requested attribute
00126  * \param addr requested neighbor
00127  * \retval     pointer to data, NULL if neighbor was not found
00128  *
00129  *             Searches neighbor table for addr and returns pointer to data section
00130  *             specified by attribute type and addr.
00131  *             This pointer should not be saved, as it may point to data from another
00132  *             neighbor in the future if neighbors get removed/added over time.
00133  */
00134 void *neighbor_attr_get_data(struct neighbor_attr *, const rimeaddr_t *addr);
00135 
00136 /**
00137  * \brief      Copy data to neighbor table
00138  * \retval     non-zero if successful, zero if not
00139  *
00140  *             Copies data to specific part of the neighbor table, specified by
00141  *             neighbor and attribute type, and resets timeout for that neighbor.
00142  *             If neighbor was not found, this will add a new neighbor to the table.
00143  */
00144 int neighbor_attr_set_data(struct neighbor_attr *, const rimeaddr_t *addr,
00145                            void *data);
00146 
00147 /**
00148  * \brief      Set global lifetime of neighbor entries.
00149  * \param      Lifetime in seconds. If 0, entries will not time out
00150  */
00151 void neighbor_attr_set_timeout(uint16_t);
00152 
00153 /**
00154  * \brief      get global lifetime of neighbor entries. If 0, entries will not time out
00155  */
00156 uint16_t neighbor_attr_get_timeout(void);
00157 
00158 /**
00159  * \brief      reset timeout of a neighbor to prevent it from being removed
00160  */
00161 void neighbor_attr_tick(const rimeaddr_t *);
00162 
00163 #endif                          /* NEIGHBORATTR_H_ */