Contiki 2.6
|
00001 /** 00002 * \addtogroup rime 00003 * @{ 00004 */ 00005 00006 /** 00007 * \defgroup rimeipolite Ipolite best effort local broadcast 00008 * @{ 00009 * 00010 * The ipolite module sends one local area broadcast packet within one 00011 * time interval. If a packet with the same header is received from a 00012 * neighbor within the interval, the packet is not sent. 00013 * 00014 * The polite primitive is a generalization of the polite gossip 00015 * algorithm from Trickle (Levis et al, NSDI 2004). The polite gossip 00016 * algorithm is designed to reduce the total amount of packet 00017 * transmissions by not repeating a message that other nodes have 00018 * already sent. The purpose of the polite broadcast primitive is to 00019 * avoid that multiple copies of a specific set of packet attributes 00020 * is sent on a specified logical channel in the local neighborhood 00021 * during a time interval. 00022 * 00023 * The polite broadcast primitive is useful for implementing broadcast 00024 * protocols that use, e.g., negative acknowledgements. If many nodes 00025 * need to send the negative acknowledgement to a sender, it is enough 00026 * if only a single message is delivered to the sender. 00027 * 00028 * The upper layer protocol or application that uses the polite 00029 * broadcast primitive provides an interval time, and message along 00030 * with a list of packet attributes for which multiple copies should 00031 * be avoided. The polite broadcast primitive stores the outgoing 00032 * message in a queue buffer, stores the list of packet attributes, 00033 * and sets up a timer. The timer is set to a random time during the 00034 * second half of the interval time. 00035 * 00036 * During the first half of the time interval, the sender listens for 00037 * other transmissions. If it hears a packet that matches the 00038 * attributes provided by the upper layer protocol or application, the 00039 * sender drops the packet. The send timer has been set to a random 00040 * time some time during the second half of the interval. When the 00041 * timer fires, and the sender has not yet heard a transmission of the 00042 * same packet attributes, the sender broadcasts its packet to all its 00043 * neighbors. 00044 * 00045 * The polite broadcast module does not add any packet attributes to 00046 * outgoing packets apart from those added by the upper layer. 00047 * 00048 * \section channels Channels 00049 * 00050 * The ipolite module uses 1 channel. 00051 * 00052 */ 00053 00054 /* 00055 * Copyright (c) 2007, Swedish Institute of Computer Science. 00056 * All rights reserved. 00057 * 00058 * Redistribution and use in source and binary forms, with or without 00059 * modification, are permitted provided that the following conditions 00060 * are met: 00061 * 1. Redistributions of source code must retain the above copyright 00062 * notice, this list of conditions and the following disclaimer. 00063 * 2. Redistributions in binary form must reproduce the above copyright 00064 * notice, this list of conditions and the following disclaimer in the 00065 * documentation and/or other materials provided with the distribution. 00066 * 3. Neither the name of the Institute nor the names of its contributors 00067 * may be used to endorse or promote products derived from this software 00068 * without specific prior written permission. 00069 * 00070 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND 00071 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 00072 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 00073 * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE 00074 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 00075 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 00076 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 00077 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 00078 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 00079 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 00080 * SUCH DAMAGE. 00081 * 00082 * This file is part of the Contiki operating system. 00083 * 00084 * $Id: ipolite.h,v 1.12 2010/06/14 19:19:17 adamdunkels Exp $ 00085 */ 00086 00087 /** 00088 * \file 00089 * Header file for Ipolite best effort local Broadcast (ipolite) 00090 * \author 00091 * Adam Dunkels <adam@sics.se> 00092 */ 00093 00094 #ifndef __IPOLITE_H__ 00095 #define __IPOLITE_H__ 00096 00097 #include "sys/ctimer.h" 00098 00099 #include "net/rime/broadcast.h" 00100 #include "net/queuebuf.h" 00101 00102 struct ipolite_conn; 00103 00104 #define IPOLITE_ATTRIBUTES IBC_ATTRIBUTES 00105 00106 /** 00107 * \brief A structure with callback functions for an ipolite connection. 00108 * 00109 * This structure holds a list of callback functions used 00110 * a an ipolite connection. The functions are called when 00111 * events occur on the connection. 00112 * 00113 */ 00114 struct ipolite_callbacks { 00115 /** 00116 * Called when a packet is received on the connection. 00117 */ 00118 void (* recv)(struct ipolite_conn *c, const rimeaddr_t *from); 00119 00120 /** 00121 * Called when a packet is sent on the connection. 00122 */ 00123 void (* sent)(struct ipolite_conn *c); 00124 00125 /** 00126 * Called when a packet is dropped because a packet was heard from a 00127 * neighbor. 00128 */ 00129 void (* dropped)(struct ipolite_conn *c); 00130 }; 00131 00132 /** 00133 * An opaque structure with no user-visible elements that holds the 00134 * state of an ipolite connection, 00135 */ 00136 struct ipolite_conn { 00137 struct broadcast_conn c; 00138 const struct ipolite_callbacks *cb; 00139 struct ctimer t; 00140 struct queuebuf *q; 00141 uint8_t hdrsize; 00142 uint8_t maxdups; 00143 uint8_t dups; 00144 }; 00145 00146 00147 /** 00148 * \brief Open an ipolite connection 00149 * \param c A pointer to a struct ipolite_conn. 00150 * \param channel The channel number to be used for this connection 00151 * \param maxdups The number of duplicates that are allowed to be heard before suppressing 00152 * \param cb A pointer to the callbacks used for this connection 00153 * 00154 * This function opens an ipolite connection on the 00155 * specified channel. The callbacks are called when a 00156 * packet is received, or when another event occurs on the 00157 * connection (see \ref "struct ipolite_callbacks"). 00158 */ 00159 void ipolite_open(struct ipolite_conn *c, uint16_t channel, uint8_t maxdups, 00160 const struct ipolite_callbacks *cb); 00161 00162 /** 00163 * \brief Close an ipolite connection 00164 * \param c A pointer to a struct ipolite_conn that has previously been opened with ipolite_open(). 00165 * 00166 * This function closes an ipolite connection that has 00167 * previously been opened with ipolite_open(). 00168 */ 00169 void ipolite_close(struct ipolite_conn *c); 00170 00171 /** 00172 * \brief Send a packet on an ipolite connection. 00173 * \param c A pointer to a struct ipolite_conn that has previously been opened with ipolite_open(). 00174 * \param interval The timer interval in which the packet should be sent. 00175 * \param hdrsize The size of the header that should be unique within the time interval. 00176 * 00177 * This function sends a packet from the packetbuf on the 00178 * ipolite connection. The packet is sent some time during 00179 * the time interval, but only if no other packet is 00180 * received with the same header. 00181 * 00182 */ 00183 int ipolite_send(struct ipolite_conn *c, clock_time_t interval, 00184 uint8_t hdrsize); 00185 00186 /** 00187 * \brief Cancel a pending packet 00188 * \param c A pointer to a struct ipolite_conn that has previously been opened with ipolite_open(). 00189 * 00190 * This function cancels a pending transmission that has 00191 * previously been started with ipolite_send(). 00192 */ 00193 void ipolite_cancel(struct ipolite_conn *c); 00194 00195 #endif /* __IPOLITE_H__ */ 00196 00197 /** @} */ 00198 /** @} */