Contiki 2.6
|
00001 /** 00002 * \addtogroup rime 00003 * @{ 00004 */ 00005 00006 /** 00007 * \defgroup rimepolite Polite anonymous best effort local broadcast 00008 * @{ 00009 * 00010 * The polite 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 polite 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: polite.h,v 1.10 2010/06/18 08:28:56 nifi Exp $ 00085 */ 00086 00087 /** 00088 * \file 00089 * Header file for Polite Anonymous best effort local Broadcast (polite) 00090 * \author 00091 * Adam Dunkels <adam@sics.se> 00092 */ 00093 00094 #ifndef __POLITE_H__ 00095 #define __POLITE_H__ 00096 00097 #include "net/rime/abc.h" 00098 #include "net/queuebuf.h" 00099 #include "sys/ctimer.h" 00100 00101 struct polite_conn; 00102 00103 #define POLITE_ATTRIBUTES ABC_ATTRIBUTES 00104 00105 /** 00106 * \brief A structure with callback functions for a polite connection. 00107 * 00108 * This structure holds a list of callback functions used 00109 * a a polite connection. The functions are called when 00110 * events occur on the connection. 00111 * 00112 */ 00113 struct polite_callbacks { 00114 /** 00115 * Called when a packet is received on the connection. 00116 */ 00117 void (* recv)(struct polite_conn *c); 00118 00119 /** 00120 * Called when a packet is sent on the connection. 00121 */ 00122 void (* sent)(struct polite_conn *c); 00123 00124 /** 00125 * Called when a packet is dropped because a packet was heard from a 00126 * neighbor. 00127 */ 00128 void (* dropped)(struct polite_conn *c); 00129 }; 00130 00131 /** 00132 * An opaque structure with no user-visible elements that holds the 00133 * state of a polite connection, 00134 */ 00135 struct polite_conn { 00136 struct abc_conn c; 00137 const struct polite_callbacks *cb; 00138 struct ctimer t; 00139 struct queuebuf *q; 00140 uint8_t hdrsize; 00141 }; 00142 00143 /** 00144 * \brief Open a polite connection 00145 * \param c A pointer to a struct polite_conn. 00146 * \param channel The channel number to be used for this connection 00147 * \param cb A pointer to the callbacks used for this connection 00148 * 00149 * This function opens a polite connection on the 00150 * specified channel. The callbacks are called when a 00151 * packet is received, or when another event occurs on the 00152 * connection (see \ref "struct polite_callbacks"). 00153 */ 00154 void polite_open(struct polite_conn *c, uint16_t channel, 00155 const struct polite_callbacks *cb); 00156 00157 /** 00158 * \brief Close a polite connection 00159 * \param c A pointer to a struct polite_conn that has previously been opened with polite_open(). 00160 * 00161 * This function closes a polite connection that has 00162 * previously been opened with polite_open(). 00163 */ 00164 void polite_close(struct polite_conn *c); 00165 00166 00167 /** 00168 * \brief Send a packet on a polite connection. 00169 * \param c A pointer to a struct polite_conn that has previously been opened with polite_open(). 00170 * \param interval The timer interval in which the packet should be sent. 00171 * \param hdrsize The size of the header that should be unique within the time interval. 00172 * 00173 * This function sends a packet from the packetbuf on the 00174 * polite connection. The packet is sent some time during 00175 * the time interval, but only if no other packet is 00176 * received with the same header. 00177 * 00178 */ 00179 int polite_send(struct polite_conn *c, clock_time_t interval, uint8_t hdrsize); 00180 00181 /** 00182 * \brief Cancel a pending packet 00183 * \param c A pointer to a struct polite_conn that has previously been opened with polite_open(). 00184 * 00185 * This function cancels a pending transmission that has 00186 * previously been started with polite_send(). 00187 */ 00188 void polite_cancel(struct polite_conn *c); 00189 00190 #endif /* __POLITE_H__ */ 00191 00192 /** @} */ 00193 /** @} */