Contiki 2.6
|
00001 /** 00002 * \addtogroup rime 00003 * @{ 00004 */ 00005 00006 /** 00007 * \defgroup rimeannouncement Announcements 00008 * @{ 00009 * 00010 * The Announcement primitive does local area announcements. An 00011 * announcement is an (ID, value) tuple that is disseminated to local 00012 * area neighbors. An application or protocol can explicitly listen to 00013 * announcements from neighbors. When an announcement is heard, a 00014 * callback is invoked. 00015 * 00016 * Announcements can be used for a variety of network mechanisms such 00017 * as neighbor discovery, node-level service discovery, or routing 00018 * metric dissemination. 00019 * 00020 * Application programs and protocols register announcements with the 00021 * announcement module. An announcement back-end, implemented by the 00022 * system, takes care of sending out announcements over the radio, as 00023 * well as collecting announcements heard from neighbors. 00024 * 00025 */ 00026 00027 /* 00028 * Copyright (c) 2008, Swedish Institute of Computer Science. 00029 * All rights reserved. 00030 * 00031 * Redistribution and use in source and binary forms, with or without 00032 * modification, are permitted provided that the following conditions 00033 * are met: 00034 * 1. Redistributions of source code must retain the above copyright 00035 * notice, this list of conditions and the following disclaimer. 00036 * 2. Redistributions in binary form must reproduce the above copyright 00037 * notice, this list of conditions and the following disclaimer in the 00038 * documentation and/or other materials provided with the distribution. 00039 * 3. Neither the name of the Institute nor the names of its contributors 00040 * may be used to endorse or promote products derived from this software 00041 * without specific prior written permission. 00042 * 00043 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND 00044 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 00045 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 00046 * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE 00047 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 00048 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 00049 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 00050 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 00051 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 00052 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 00053 * SUCH DAMAGE. 00054 * 00055 * This file is part of the Contiki operating system. 00056 * 00057 * $Id: announcement.h,v 1.8 2010/03/25 08:49:56 adamdunkels Exp $ 00058 */ 00059 00060 /** 00061 * \file 00062 * Header file for the announcement primitive 00063 * \author 00064 * Adam Dunkels <adam@sics.se> 00065 */ 00066 00067 #ifndef __ANNOUNCEMENT_H__ 00068 #define __ANNOUNCEMENT_H__ 00069 00070 #include "net/rime/rimeaddr.h" 00071 00072 struct announcement; 00073 00074 typedef void (*announcement_callback_t)(struct announcement *a, 00075 const rimeaddr_t *from, 00076 uint16_t id, uint16_t val); 00077 00078 /** 00079 * \brief Representation of an announcement. 00080 * 00081 * This structure holds the state of an announcement. It 00082 * is an opaque structure with no user-visible elements. 00083 */ 00084 struct announcement { 00085 struct announcement *next; 00086 uint16_t id; 00087 uint16_t value; 00088 announcement_callback_t callback; 00089 uint8_t has_value; 00090 }; 00091 00092 /** 00093 * \name Application API 00094 * @{ 00095 */ 00096 /** 00097 * \brief Register an announcement 00098 * \param a A pointer to a struct announcement 00099 * \param id The identifying number of the announcement 00100 * \param callback A pointer to a callback function that is called 00101 * when an announcement is heard 00102 * 00103 * This function registers an announcement with the 00104 * announcement module. The state of the announcement is 00105 * held in a struct announcement variable, which is passed 00106 * as an argument to this function. This variable must be 00107 * allocated by the caller. An announcement is identified 00108 * with a 16-bit number, which is passed as a parameter to 00109 * the function. The announcement also has an initial 00110 * value, that can later be changed with 00111 * announcement_set_value(). 00112 * 00113 */ 00114 void announcement_register(struct announcement *a, 00115 uint16_t id, 00116 announcement_callback_t callback); 00117 00118 /** 00119 * \brief Remove a previously registered announcement 00120 * \param a A pointer to a struct announcement that has 00121 * previously been registered 00122 * 00123 * This function removes an announcement that has 00124 * previously been registered with 00125 * announcement_register(). 00126 * 00127 */ 00128 void announcement_remove(struct announcement *a); 00129 00130 00131 /** 00132 * \brief Set the value of an announcement 00133 * \param a A pointer to a struct announcement that has 00134 * previously been registered 00135 * 00136 * This function sets the value of an announcement that 00137 * has previously been registered with 00138 * announcement_register(). 00139 * 00140 */ 00141 void announcement_set_value(struct announcement *a, uint16_t value); 00142 00143 /** 00144 * \brief Remove the value of an announcement 00145 * \param a A pointer to a struct announcement that has 00146 * previously been registered 00147 * 00148 * This function removes the value of an announcement that 00149 * has previously been registered with 00150 * announcement_register(). 00151 * 00152 */ 00153 void announcement_remove_value(struct announcement *a); 00154 00155 00156 /** 00157 * \brief Bump an announcement 00158 * \param a A pointer to a struct announcement that has 00159 * previously been registered 00160 * 00161 * This function is called to inform the announcement 00162 * module that a particular announcement has changed in a 00163 * way that it should be bumped. When an announcement is 00164 * bumped, the announcement back-end may send out a new 00165 * announcement to neighbors. 00166 * 00167 */ 00168 void announcement_bump(struct announcement *a); 00169 00170 /** 00171 * \brief Listen for announcements for a specific amount of 00172 * announcement periods 00173 * \param periods The number of periods to listen for announcement 00174 * 00175 * This function starts to listen for announcements for 00176 * the specified amount of announcement periods. This 00177 * function is called to ensure that the announcement 00178 * module hears announcements from neighbors. The 00179 * announcement module may hear announcements even if 00180 * listening is not explicitly enabled, but with listening 00181 * enabled, more announcements will be heard. 00182 * 00183 */ 00184 void announcement_listen(int periods); 00185 /** 00186 * @} 00187 */ 00188 00189 /** 00190 * \name System API 00191 * @{ 00192 */ 00193 00194 /** 00195 * \brief Initialize the announcement module 00196 * 00197 * This function initializes the announcement module, and 00198 * is called by the system at boot up. 00199 */ 00200 void announcement_init(void); 00201 00202 /** 00203 * \brief Get the list of registered announcements 00204 * \return The list of registered announcements 00205 * 00206 * This function returns the list of registered 00207 * announcements. This function is used by the back-end to 00208 * compile announcement packets from the registered 00209 * announcements. 00210 * 00211 * The announcement list is an ordinary Contiki list, as 00212 * defined by the \ref list "list module". 00213 * 00214 */ 00215 struct announcement *announcement_list(void); 00216 00217 /** 00218 * \brief Inform the announcement module of an incoming announcement 00219 * \param from The address of the sender of the announcement 00220 * \param id The identifier of the announcement 00221 * \param value The value of the announcement 00222 * 00223 * This function is called by the back-end to inform the 00224 * announcement module that an announcement from a 00225 * neighbor has been heard. 00226 * 00227 */ 00228 void announcement_heard(const rimeaddr_t *from, uint16_t id, uint16_t value); 00229 00230 /** 00231 * \brief Register a listen callback with the announcement module 00232 * \param callback A pointer to a callback function 00233 * 00234 * This function is called by the back-end to register a 00235 * listen callback with the announcement module. The 00236 * listen callback function is called by the announcement 00237 * module as part of the announcement_listen() function. 00238 * 00239 */ 00240 void announcement_register_listen_callback(void (*callback)(int time)); 00241 00242 enum { 00243 ANNOUNCEMENT_NOBUMP, 00244 ANNOUNCEMENT_BUMP, 00245 }; 00246 00247 typedef void (* announcement_observer)(uint16_t id, uint8_t has_value, 00248 uint16_t newvalue, uint16_t oldvalue, 00249 uint8_t bump); 00250 00251 /** 00252 * \brief Register an observer callback with the announcement module 00253 * \param observer A pointer to an observer function 00254 * 00255 * This function is callback by the back-end to register 00256 * an observer callback with the announcement module. The 00257 * observer callback is called by the announcement module 00258 * when an announcement is registered, removed, or have 00259 * its identifier or value updated. 00260 * 00261 * The back-end may chose to send out a new announcement 00262 * message with the updated values. 00263 * 00264 */ 00265 void announcement_register_observer_callback(announcement_observer observer); 00266 00267 /** 00268 * @} 00269 */ 00270 00271 #endif /* __ANNOUNCE_H__ */ 00272 00273 /** @} */ 00274 /** @} */