Difference between revisions of "Packetbuffer Basics"

Revision as of 17:39, 4 November 2014

Back to Contiki Tutorials

Introduction

This tutorial is a introduction to different operations on the packetbuf on ContikiOS 2.7. We will also cover brief details about each of the functions and how they work.

You will learn

Through this tutorial you will learn about different funcions and usage components of packetbuf. This will help you in any projects since packetpuf is necessary for any networking project.

Source Codes

~/contiki-2.7/core/net/packetbuf.c

~/contiki-2.7/core/net/packetbuf.h

Description

void packetbuf_clear(void);

/**

* \brief      Clear and reset the header of the packetbuf
*
*             This function clears the header of the packetbuf and
*             resets all the internal state pointers pertaining to
*             the header (header size, header pointer, but not
*             external data pointer). It is used before after sending
*             a packet in the packetbuf, to be able to reuse the
*             packet buffer for a later retransmission.
*
*/

void packetbuf_clear_hdr(void);

void packetbuf_hdr_remove(int bytes);

/**

* \brief      Get a pointer to the data in the packetbuf
* \return     Pointer to the packetbuf data
*
*             This function is used to get a pointer to the data in
*             the packetbuf. The data is either stored in the packetbuf,
*             or referenced to an external location.
*
*             For outbound packets, the packetbuf consists of two
*             parts: header and data. The header is accessed with the
*             packetbuf_hdrptr() function.
*
*             For incoming packets, both the packet header and the
*             packet data is stored in the data portion of the
*             packetbuf. Thus this function is used to get a pointer to
*             the header for incoming packets.
*
*/

void *packetbuf_dataptr(void);

/**

* \brief      Get a pointer to the header in the packetbuf, for outbound packets
* \return     Pointer to the packetbuf header
*
*             For outbound packets, the packetbuf consists of two
*             parts: header and data. This function is used to get a
*             pointer to the header in the packetbuf. The header is
*             stored in the packetbuf.
*
*/

void *packetbuf_hdrptr(void);

/**

* \brief      Get the length of the header in the packetbuf, for outbound packets
* \return     Length of the header in the packetbuf
*
*             For outbound packets, the packetbuf consists of two
*             parts: header and data. This function is used to get
*             the length of the header in the packetbuf. The header is
*             stored in the packetbuf and accessed via the
*             packetbuf_hdrptr() function.
*
*/

uint8_t packetbuf_hdrlen(void);

/**

* \brief      Get the length of the data in the packetbuf
* \return     Length of the data in the packetbuf
*
*             For outbound packets, the packetbuf consists of two
*             parts: header and data. This function is used to get
*             the length of the data in the packetbuf. The data is
*             stored in the packetbuf and accessed via the
*             packetbuf_dataptr() function.
*
*             For incoming packets, both the packet header and the
*             packet data is stored in the data portion of the
*             packetbuf. This function is then used to get the total
*             length of the packet - both header and data.
*
*/

uint16_t packetbuf_datalen(void);

/**

* \brief      Get the total length of the header and data in the packetbuf
* \return     Length of data and header in the packetbuf
*
*/

uint16_t packetbuf_totlen(void);

/**

* \brief      Set the length of the data in the packetbuf
* \param len  The length of the data
*
*             For outbound packets, the packetbuf consists of two
*             parts: header and data. This function is used to set
*             the length of the data in the packetbuf.
*/

void packetbuf_set_datalen(uint16_t len);

/**

* \brief      Point the packetbuf to external data
* \param ptr  A pointer to the external data
* \param len  The length of the external data
*
*             For outbound packets, the packetbuf consists of two
*             parts: header and data. This function is used to make
*             the packetbuf point to external data. The function also
*             specifies the length of the external data that the
*             packetbuf references.
*/

void packetbuf_reference(void *ptr, uint16_t len);

/**

* \brief      Check if the packetbuf references external data
* \retval     Non-zero if the packetbuf references external data, zero otherwise.
*
*             For outbound packets, the packetbuf consists of two
*             parts: header and data. This function is used to check
*             if the packetbuf points to external data that has
*             previously been referenced with packetbuf_reference().
*
*/

int packetbuf_is_reference(void);

/**

* \brief      Get a pointer to external data referenced by the packetbuf
* \retval     A pointer to the external data
*
*             For outbound packets, the packetbuf consists of two
*             parts: header and data. The data may point to external
*             data that has previously been referenced with
*             packetbuf_reference(). This function is used to get a
*             pointer to the external data.
*
*/

void *packetbuf_reference_ptr(void);

/**

* \brief      Compact the packetbuf
*
*             This function compacts the packetbuf by copying the data
*             portion of the packetbuf so that becomes consecutive to
*             the header. It also copies external data that has
*             previously been referenced with packetbuf_reference()
*             into the packetbuf.
*
*             This function is called by the Rime code before a
*             packet is to be sent by a device driver. This assures
*             that the entire packet is consecutive in memory.
*
*/

void packetbuf_compact(void);

/**

* \brief      Copy from external data into the packetbuf
* \param from A pointer to the data from which to copy
* \param len  The size of the data to copy
* \retval     The number of bytes that was copied into the packetbuf
*
*             This function copies data from a pointer into the
*             packetbuf. If the data that is to be copied is larger
*             than the packetbuf, only the data that fits in the
*             packetbuf is copied. The number of bytes that could be
*             copied into the rimbuf is returned.
*
*/

int packetbuf_copyfrom(const void *from, uint16_t len);

/**

* \brief      Copy the entire packetbuf to an external buffer
* \param to   A pointer to the buffer to which the data is to be copied
* \retval     The number of bytes that was copied to the external buffer
*
*             This function copies the packetbuf to an external
*             buffer. Both the data portion and the header portion of
*             the packetbuf is copied. If the packetbuf referenced
*             external data (referenced with packetbuf_reference()) the
*             external data is copied.
*
*             The external buffer to which the packetbuf is to be
*             copied must be able to accomodate at least
*             (PACKETBUF_SIZE + PACKETBUF_HDR_SIZE) bytes. The number of
*             bytes that was copied to the external buffer is
*             returned.
*
*/

int packetbuf_copyto(void *to);

/**

* \brief      Copy the header portion of the packetbuf to an external buffer
* \param to   A pointer to the buffer to which the data is to be copied
* \retval     The number of bytes that was copied to the external buffer
*
*             This function copies the header portion of the packetbuf
*             to an external buffer.
*
*             The external buffer to which the packetbuf is to be
*             copied must be able to accomodate at least
*             PACKETBUF_HDR_SIZE bytes. The number of bytes that was
*             copied to the external buffer is returned.
*
*/

int packetbuf_copyto_hdr(uint8_t *to);

/**

* \brief      Extend the header of the packetbuf, for outbound packets
* \param size The number of bytes the header should be extended
* \retval     Non-zero if the header could be extended, zero otherwise
*
*             This function is used to allocate extra space in the
*             header portion in the packetbuf, when preparing outbound
*             packets for transmission. If the function is unable to
*             allocate sufficient header space, the function returns
*             zero and does not allocate anything.
*
*/

int packetbuf_hdralloc(int size);

/**

* \brief      Reduce the header in the packetbuf, for incoming packets
* \param size The number of bytes the header should be reduced
* \retval     Non-zero if the header could be reduced, zero otherwise
*
*             This function is used to remove the first part of the
*             header in the packetbuf, when processing incoming
*             packets. If the function is unable to remove the
*             requested amount of header space, the function returns
*             zero and does not allocate anything.
*
*/

int packetbuf_hdrreduce(int size);