Contiki 2.6

runicast.h

Go to the documentation of this file.
00001 /**
00002  * \addtogroup rime
00003  * @{
00004  */
00005 
00006 /**
00007  * \defgroup rimerunicast Single-hop reliable unicast
00008  * @{
00009  *
00010  * The reliable single-hop unicast primitive (runicast) reliably sends
00011  * a packet to a single-hop neighbor.  The runicast primitive uses
00012  * acknowledgements and retransmissions to ensure that the neighbor
00013  * successfully receives the packet.  When the receiver has
00014  * acknowledged the packet, the ruc module notifies the sending
00015  * application via a callback.  The ruc primitive uses the stubborn
00016  * single-hop unicast primitive to do retransmissions.  Thus, the ruc
00017  * primitive does not have to manage the details of setting up timers
00018  * and doing retransmissions, but can concentrate on dealing with
00019  * acknowledgements.
00020  *
00021  * The runicast primitive adds two packet attributes: the single-hop
00022  * packet type and the single-hop packet ID.  The runicast primitive
00023  * uses the packet ID attribute as a sequence number for matching
00024  * acknowledgement packets to the corresponding data packets.
00025  *
00026  * The application or protocol that uses the runicast primitive can
00027  * specify the maximum number of transmissions that the ruc module
00028  * should attempt before the packet times out.  If a packet times out,
00029  * the application or protocol that sent the packet is notified with a
00030  * callback.
00031  *
00032  *
00033  * \section channels Channels
00034  *
00035  * The runicast module uses 1 channel.
00036  *
00037  */
00038 
00039 /*
00040  * Copyright (c) 2006, Swedish Institute of Computer Science.
00041  * All rights reserved.
00042  *
00043  * Redistribution and use in source and binary forms, with or without
00044  * modification, are permitted provided that the following conditions
00045  * are met:
00046  * 1. Redistributions of source code must retain the above copyright
00047  *    notice, this list of conditions and the following disclaimer.
00048  * 2. Redistributions in binary form must reproduce the above copyright
00049  *    notice, this list of conditions and the following disclaimer in the
00050  *    documentation and/or other materials provided with the distribution.
00051  * 3. Neither the name of the Institute nor the names of its contributors
00052  *    may be used to endorse or promote products derived from this software
00053  *    without specific prior written permission.
00054  *
00055  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
00056  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00057  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00058  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
00059  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00060  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00061  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00062  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00063  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
00064  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00065  * SUCH DAMAGE.
00066  *
00067  * This file is part of the Contiki operating system.
00068  *
00069  * $Id: runicast.h,v 1.7 2010/03/19 13:22:08 adamdunkels Exp $
00070  */
00071 
00072 /**
00073  * \file
00074  *         Reliable unicast header file
00075  * \author
00076  *         Adam Dunkels <adam@sics.se>
00077  */
00078 
00079 #ifndef __RUNICAST_H__
00080 #define __RUNICAST_H__
00081 
00082 #include "net/rime/stunicast.h"
00083 
00084 struct runicast_conn;
00085 
00086 
00087 #define RUNICAST_PACKET_ID_BITS 2
00088 
00089 #define RUNICAST_ATTRIBUTES  { PACKETBUF_ATTR_PACKET_TYPE, PACKETBUF_ATTR_BIT }, \
00090                              { PACKETBUF_ATTR_PACKET_ID, PACKETBUF_ATTR_BIT * RUNICAST_PACKET_ID_BITS }, \
00091                              STUNICAST_ATTRIBUTES
00092 struct runicast_callbacks {
00093   void (* recv)(struct runicast_conn *c, const rimeaddr_t *from, uint8_t seqno);
00094   void (* sent)(struct runicast_conn *c, const rimeaddr_t *to, uint8_t retransmissions);
00095   void (* timedout)(struct runicast_conn *c, const rimeaddr_t *to, uint8_t retransmissions);
00096 };
00097 
00098 struct runicast_conn {
00099   struct stunicast_conn c;
00100   const struct runicast_callbacks *u;
00101   uint8_t sndnxt;
00102   uint8_t is_tx;
00103   uint8_t rxmit;
00104   uint8_t max_rxmit;
00105 };
00106 
00107 void runicast_open(struct runicast_conn *c, uint16_t channel,
00108                const struct runicast_callbacks *u);
00109 void runicast_close(struct runicast_conn *c);
00110 
00111 int runicast_send(struct runicast_conn *c, const rimeaddr_t *receiver,
00112                   uint8_t max_retransmissions);
00113 
00114 uint8_t runicast_is_transmitting(struct runicast_conn *c);
00115 
00116 #endif /* __RUNICAST_H__ */
00117 /** @} */
00118 /** @} */