Contiki 2.6

announcement.h

Go to the documentation of this file.
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 /** @} */