contiki/core/net/rime/packetqueue.h

/*
 * Copyright (c) 2009, Swedish Institute of Computer Science.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in the
 *    documentation and/or other materials provided with the distribution.
 * 3. Neither the name of the Institute nor the names of its contributors
 *    may be used to endorse or promote products derived from this software
 *    without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 * SUCH DAMAGE.
 *
 * This file is part of the Contiki operating system.
 *
 */

/**
 * \file
 *         Header file for the packetqueue module
 * \author
 *         Adam Dunkels <adam@sics.se>
 */

/**
 * \addtogroup rime
 * @{
 */

/**
 * \defgroup packetqueue Packet queue
 * @{
 *
 * The packetqueue module handles a list of queued packets.
 *
 */

#ifndef PACKETQUEUE_H_
#define PACKETQUEUE_H_

#include "lib/list.h"
#include "lib/memb.h"

#include "sys/ctimer.h"

#include "net/packetbuf.h"
#include "net/queuebuf.h"

/**
 * \brief      Representation of a packet queue.
 *
 *             This structure holds the state of a packet queue. It is
 *             an opaque structure with no user-visible elements.
 */
struct packetqueue {
  list_t *list;
  struct memb *memb;
};

/**
 * \brief      Representation of an item in a packet queue.
 *
 *             This structure holds the state of a packet queue. It is
 *             an opaque structure with no user-visible elements. The
 *             function packetqueue_queuebuf() is used to extract a
 *             "queubuf" from the item. The function
 *             packetqueue_ptr() is used to extract the opaque pointer
 *             that was registered with the
 *             packetqueue_enqueue_packetbuf() function.
 */
struct packetqueue_item {
  struct packetqueue_item *next;
  struct queuebuf *buf;
  struct packetqueue *queue;
  struct ctimer lifetimer;
  void *ptr;
};


/**
 * \brief      Define a packet queue.
 * \param name The variable name of the packet queue
 * \param size The maximum size of the packet queue
 *
 *             This statement defines a packet queue. A packet queue
 *             is defined on a per-module basis.
 *
 */
#define PACKETQUEUE(name, size) LIST(name##_list); \
                                MEMB(name##_memb, struct packetqueue_item, size); \
				static struct packetqueue name = { &name##_list, \
								   &name##_memb }

/**
 * \name Packet queue functions.
 * @{
 */
/**
 * \brief      Initialize a packet queue.
 * \param q    A pointer to a struct packetqueue that was defined with PACKETQUEUE().
 *
 *             This function initializes a packetqueue that has
 *             previously been defined with PACKETQUEUE().
 *
 */
void packetqueue_init(struct packetqueue *q);


/**
 * \brief      Enqueue a packetbuf on a packet queue.
 * \param q    A pointer to a struct packetqueue.
 * \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.
 * \param ptr  An opaque, user-defined pointer that can be used to identify the packet when it later is dequeued.
 * \retval Zero   If memory could not be allocated for the packet.
 * \retval Non-zero If the packet was successfully enqueued.
 *
 *
 *             This function enqueues the \ref packetbuf "packetbuf"
 *             to the packet queue pointed to by the q parameter. The
 *             packet queue must previously have been defined with
 *             PACKETQUEUE() and initialized with packetqueue_init().
 *
 *             Each packet queue item has a maximum lifetime. When the
 *             lifetime expires, the packet queue item is
 *             automatically removed from the packet queue. If the
 *             lifetime parameter is given as zero, the packet never
 *             times out from the packet queue.
 *
 *             Each packet queue item is tagged with a user-defined
 *             pointer. This pointer can be used to identify packets
 *             as they later are dequeued from the queue. This is
 *             useful if two modules is using the same packet queue:
 *             the modules can use the pointer to distinguish to which
 *             module a dequeued packet belongs.
 *
 */
int packetqueue_enqueue_packetbuf(struct packetqueue *q, clock_time_t lifetime,
				  void *ptr);

/**
 * \brief      Access the first item on the packet buffer.
 * \param q    A pointer to a struct packetqueue.
 * \return     A pointer to the first item on the packet queue.
 *
 *             This function returns the first item on the packet
 *             queue. The packet queue is unchanged by this
 *             function. To dequeue the first item on the list, use
 *             the packetqueue_dequeue() function.
 *
 */
struct packetqueue_item *packetqueue_first(struct packetqueue *q);

/**
 * \brief      Remove the first item on the packet buffer.
 * \param q    A pointer to a struct packetqueue.
 *
 *             This function removes the first item on the packet
 *             queue. The function does not return the first item: to
 *             access the first item, the packetqueue_first() function
 *             must have been used prior to calling
 *             packetqueue_dequeue().
 *
 */
void packetqueue_dequeue(struct packetqueue *q);

/**
 * \brief      Get the length of the packet queue
 * \param q    A pointer to a struct packetqueue.
 * \return     The number of packets queued on the packet queue
 *
 *             This function returns the number of packets that are
 *             queued on the packet queue.
 *
 */
int packetqueue_len(struct packetqueue *q);

/**
 * @}
 */

/**
 * \name Packet queue item functions
 * @{
 */

/**
 * \brief      Access the queuebuf in a packet queue item.
 * \param i    A packet queue item, obtained with packetqueue_first().
 * \return     A pointer to the queuebuf in the packet queue item.
 */
struct queuebuf *packetqueue_queuebuf(struct packetqueue_item *i);
/**
 * \brief      Access the user-defined pointer in a packet queue item.
 * \param i    A packet queue item, obtained with packetqueue_first().
 * \return     A pointer to the user-defined pointer in the packet queue item.
 */

void *packetqueue_ptr(struct packetqueue_item *i);
/**
 * @}
 */


#endif /* PACKETQUEUE_H_ */

/** @} */
/** @} */