Contiki 2.5
packetqueue.h
Go to the documentation of this file.
1 /**
2  * \addtogroup rime
3  * @{
4  */
5 
6 /**
7  * \defgroup packetqueue Packet queue
8  * @{
9  *
10  * The packetqueue module handles a list of queued packets.
11  *
12  */
13 
14 /*
15  * Copyright (c) 2009, Swedish Institute of Computer Science.
16  * All rights reserved.
17  *
18  * Redistribution and use in source and binary forms, with or without
19  * modification, are permitted provided that the following conditions
20  * are met:
21  * 1. Redistributions of source code must retain the above copyright
22  * notice, this list of conditions and the following disclaimer.
23  * 2. Redistributions in binary form must reproduce the above copyright
24  * notice, this list of conditions and the following disclaimer in the
25  * documentation and/or other materials provided with the distribution.
26  * 3. Neither the name of the Institute nor the names of its contributors
27  * may be used to endorse or promote products derived from this software
28  * without specific prior written permission.
29  *
30  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
31  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
32  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
33  * ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
34  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
35  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
36  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
37  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
38  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
39  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
40  * SUCH DAMAGE.
41  *
42  * This file is part of the Contiki operating system.
43  *
44  * $Id: packetqueue.h,v 1.1 2010/06/14 19:19:16 adamdunkels Exp $
45  */
46 
47 /**
48  * \file
49  * Header file for the packetqueue module
50  * \author
51  * Adam Dunkels <adam@sics.se>
52  */
53 
54 #ifndef __PACKETQUEUE_H__
55 #define __PACKETQUEUE_H__
56 
57 #include "lib/list.h"
58 #include "lib/memb.h"
59 
60 #include "sys/ctimer.h"
61 
62 #include "net/packetbuf.h"
63 #include "net/queuebuf.h"
64 
65 /**
66  * \brief Representation of a packet queue.
67  *
68  * This structure holds the state of a packet queue. It is
69  * an opaque structure with no user-visible elements.
70  */
71 struct packetqueue {
72  list_t *list;
73  struct memb *memb;
74 };
75 
76 /**
77  * \brief Representation of an item in a packet queue.
78  *
79  * This structure holds the state of a packet queue. It is
80  * an opaque structure with no user-visible elements. The
81  * function packetqueue_queuebuf() is used to extract a
82  * \ref queuebuf "queubuf" from the item. The function
83  * packetqueue_ptr() is used to extract the opaque pointer
84  * that was registered with the
85  * packetqueue_enqueue_packetbuf() function.
86  */
87 struct packetqueue_item {
88  struct packetqueue_item *next;
89  struct queuebuf *buf;
90  struct packetqueue *queue;
91  struct ctimer lifetimer;
92  void *ptr;
93 };
94 
95 
96 /**
97  * \brief Define a packet queue.
98  * \param name The variable name of the packet queue
99  * \param size The maximum size of the packet queue
100  *
101  * This statement defines a packet queue. A packet queue
102  * is defined on a per-module basis.
103  *
104  */
105 #define PACKETQUEUE(name, size) LIST(name##_list); \
106  MEMB(name##_memb, struct packetqueue_item, size); \
107  static struct packetqueue name = { &name##_list, \
108  &name##_memb }
109 
110 /**
111  * \name Packet queue functions.
112  * @{
113  */
114 /**
115  * \brief Initialize a packet queue.
116  * \param q A pointer to a struct packetqueue that was defined with PACKETQUEUE().
117  *
118  * This function initializes a packetqueue that has
119  * previously been defined with PACKETQUEUE().
120  *
121  */
122 void packetqueue_init(struct packetqueue *q);
123 
124 
125 /**
126  * \brief Enqueue a packetbuf on a packet queue.
127  * \param q A pointer to a struct packetqueue.
128  * \param lifetime The maximum time that the packet should stay in the packet queue, or zero if the packet should stay on the packet queue indefinitely.
129  * \param ptr An opaque, user-defined pointer that can be used to identify the packet when it later is dequeued.
130  * \retval Zero If memory could not be allocated for the packet.
131  * \retval Non-zero If the packet was successfully enqueued.
132  *
133  *
134  * This function enqueues the \ref packetbuf "packetbuf"
135  * to the packet queue pointed to by the q parameter. The
136  * packet queue must previously have been defined with
137  * PACKETQUEUE() and initialized with packetqueue_init().
138  *
139  * Each packet queue item has a maximum lifetime. When the
140  * lifetime expires, the packet queue item is
141  * automatically removed from the packet queue. If the
142  * lifetime parameter is given as zero, the packet never
143  * times out from the packet queue.
144  *
145  * Each packet queue item is tagged with a user-defined
146  * pointer. This pointer can be used to identify packets
147  * as they later are dequeued from the queue. This is
148  * useful if two modules is using the same packet queue:
149  * the modules can use the pointer to distinguish to which
150  * module a dequeued packet belongs.
151  *
152  */
153 int packetqueue_enqueue_packetbuf(struct packetqueue *q, clock_time_t lifetime,
154  void *ptr);
155 
156 /**
157  * \brief Access the first item on the packet buffer.
158  * \param q A pointer to a struct packetqueue.
159  * \return A pointer to the first item on the packet queue.
160  *
161  * This function returns the first item on the packet
162  * queue. The packet queue is unchanged by this
163  * function. To dequeue the first item on the list, use
164  * the packetqueue_dequeue() function.
165  *
166  */
167 struct packetqueue_item *packetqueue_first(struct packetqueue *q);
168 
169 /**
170  * \brief Remove the first item on the packet buffer.
171  * \param q A pointer to a struct packetqueue.
172  *
173  * This function removes the first item on the packet
174  * queue. The function does not return the first item: to
175  * access the first item, the packetqueue_first() function
176  * must have been used prior to calling
177  * packetqueue_dequeue().
178  *
179  */
180 void packetqueue_dequeue(struct packetqueue *q);
181 
182 /**
183  * \brief Get the length of the packet queue
184  * \param q A pointer to a struct packetqueue.
185  * \return The number of packets queued on the packet queue
186  *
187  * This function returns the number of packets that are
188  * queued on the packet queue.
189  *
190  */
191 int packetqueue_len(struct packetqueue *q);
192 
193 /**
194  * @}
195  */
196 
197 /**
198  * \name Packet queue item functions
199  * @{
200  */
201 
202 /**
203  * \brief Access the queuebuf in a packet queue item.
204  * \param i A packet queue item, obtained with packetqueue_first().
205  * \return A pointer to the queuebuf in the packet queue item.
206  */
207 struct queuebuf *packetqueue_queuebuf(struct packetqueue_item *i);
208 /**
209  * \brief Access the user-defined pointer in a packet queue item.
210  * \param i A packet queue item, obtained with packetqueue_first().
211  * \return A pointer to the user-defined pointer in the packet queue item.
212  */
213 
214 void *packetqueue_ptr(struct packetqueue_item *i);
215 /**
216  * @}
217  */
218 
219 
220 #endif /* __PACKETQUEUE_H__ */
221 
222 /** @} */
223 /** @} */
Generated on Fri Aug 30 2013 12:34:05 for Contiki 2.5 by   doxygen 1.8.3.1