Network packet abstraction type and helper functions. More...

Detailed Description

Network packet abstraction type and helper functions.

Files

file  pkt.h
 General definitions for network packets and their helper functions.
 

Data Structures

struct  gnrc_pktsnip
 Type to represent parts (either headers or payload) of a packet, called snips. More...
 

Typedefs

typedef struct gnrc_pktsnip gnrc_pktsnip_t
 Type to represent parts (either headers or payload) of a packet, called snips. More...
 

Functions

static gnrc_pktsnip_tgnrc_pkt_prev_snip (gnrc_pktsnip_t *pkt, gnrc_pktsnip_t *snip)
 Returns the snip before a given snip in a packet. More...
 
static size_t gnrc_pkt_len (const gnrc_pktsnip_t *pkt)
 Calculates length of a packet in byte. More...
 
static gnrc_pktsnip_tgnrc_pkt_append (gnrc_pktsnip_t *pkt, gnrc_pktsnip_t *snip)
 Appends a snip to a packet. More...
 
static gnrc_pktsnip_tgnrc_pkt_prepend (gnrc_pktsnip_t *pkt, gnrc_pktsnip_t *snip)
 Prepends a snip to a packet. More...
 
static gnrc_pktsnip_tgnrc_pkt_delete (gnrc_pktsnip_t *pkt, gnrc_pktsnip_t *snip)
 Deletes a snip from a packet. More...
 
static size_t gnrc_pkt_len_upto (const gnrc_pktsnip_t *pkt, gnrc_nettype_t type)
 Calculates length of a packet in byte up to (including) a snip with the given type. More...
 
static size_t gnrc_pkt_count (const gnrc_pktsnip_t *pkt)
 Count the numbers of snips in the given packet. More...
 
gnrc_pktsnip_tgnrc_pktsnip_search_type (gnrc_pktsnip_t *pkt, gnrc_nettype_t type)
 Searches the packet for a packet snip of a specific type. More...
 

Typedef Documentation

◆ gnrc_pktsnip_t

typedef struct gnrc_pktsnip gnrc_pktsnip_t

Type to represent parts (either headers or payload) of a packet, called snips.

The idea behind the packet snips is that they either can represent protocol-specific headers or payload. A packet can be comprised of multiple pktsnip_t elements.

Example:

                                                    buffer
+---------------------------+                      +------+
| size = 14                 | data +-------------->|      |
| type = NETTYPE_ETHERNET   |------+               +------+
+---------------------------+                      .      .
      | next                                       .      .
      v                                            +------+
+---------------------------+         +----------->|      |
| size = 40                 | data    |            |      |
| type = NETTYPE_IPV6       |---------+            +------+
+---------------------------+                      .      .
      | next                                       .      .
      v                                            +------+
+---------------------------+            +-------->|      |
| size = 8                  | data       |         +------+
| type = NETTYPE_UDP        |------------+         .      .
+---------------------------+                      .      .
      | next                                       +------+
      v                                     +----->|      |
+---------------------------+               |      |      |
| size = 59                 | data          |      .      .
| type = NETTYPE_UNDEF      |---------------+      .      .
+---------------------------+                      .      .

To keep data duplication as low as possible the order of the snips in a packet will be reversed depending on if you send the packet or if you received it. For sending the order is from (in the network stack) lowest protocol snip to the highest, for receiving the order is from highest snip to the lowest. This way, if a layer needs to duplicate the packet a tree is created rather than a duplication of the whole package.

A very extreme example for this (we only expect one or two duplications at maximum per package) can be seen here:

 Sending                          Receiving
 =======                          =========

 * Payload                        * L2 header
 ^                                ^
 |                                |
 |\                               |\
 | * L4 header 1                  | * L2.5 header 1
 | * L3 header 1                  | * L3 header 1
 | * netif header 1               | * L4 header 1
 * L4 header 2                    | * Payload 1
 ^                                * L3 header 2
 |                                ^
 |\                               |
 | * L3 header 2                  |\
 | * L2 header 2                  | * L4 header 2
 * L2 header 3                    | * Payload 2
 |\                               * Payload 3
 | * L2 header 3
 * L2 header 4

The first three fields (next, data, size) match iolist_t (named iol_next, iol_base and iol_len there). That means that any pktsnip can be casted to iolist_t for direct passing to e.g., netdev send() functions.

Note
This type has no initializer on purpose. Please use Packet buffer as factory.

Function Documentation

◆ gnrc_pkt_append()

static gnrc_pktsnip_t* gnrc_pkt_append ( gnrc_pktsnip_t pkt,
gnrc_pktsnip_t snip 
)
inlinestatic

Appends a snip to a packet.

Parameters
[in]pktA packet.
[in]snipA snip.
Returns
The new head of pkt.

Definition at line 171 of file pkt.h.

◆ gnrc_pkt_count()

static size_t gnrc_pkt_count ( const gnrc_pktsnip_t pkt)
inlinestatic

Count the numbers of snips in the given packet.

Parameters
[in]pktfirst snip in the packet
Returns
number of snips in the given packet

Definition at line 252 of file pkt.h.

◆ gnrc_pkt_delete()

static gnrc_pktsnip_t* gnrc_pkt_delete ( gnrc_pktsnip_t pkt,
gnrc_pktsnip_t snip 
)
inlinestatic

Deletes a snip from a packet.

Parameters
[in]pktA packet.
[in]snipA snip.
Returns
The new head of pkt.

Definition at line 210 of file pkt.h.

◆ gnrc_pkt_len()

static size_t gnrc_pkt_len ( const gnrc_pktsnip_t pkt)
inlinestatic

Calculates length of a packet in byte.

Parameters
[in]pktlist of packet snips.
Returns
length of the list of headers.

Definition at line 151 of file pkt.h.

◆ gnrc_pkt_len_upto()

static size_t gnrc_pkt_len_upto ( const gnrc_pktsnip_t pkt,
gnrc_nettype_t  type 
)
inlinestatic

Calculates length of a packet in byte up to (including) a snip with the given type.

Parameters
[in]pktlist of packet snips.
[in]typetype of snip to stop calculation.
Returns
length of the list of headers.

Definition at line 228 of file pkt.h.

◆ gnrc_pkt_prepend()

static gnrc_pktsnip_t* gnrc_pkt_prepend ( gnrc_pktsnip_t pkt,
gnrc_pktsnip_t snip 
)
inlinestatic

Prepends a snip to a packet.

Parameters
[in]pktA packet.
[in]snipA snip.
Returns
The new head of pkt.

Definition at line 195 of file pkt.h.

◆ gnrc_pkt_prev_snip()

static gnrc_pktsnip_t* gnrc_pkt_prev_snip ( gnrc_pktsnip_t pkt,
gnrc_pktsnip_t snip 
)
inlinestatic

Returns the snip before a given snip in a packet.

Parameters
[in]pktA packet.
[in]snipThe snip for which the predecessor in pkt is searched for.
Returns
The snip before snip in pkt if snip is in pkt.
NULL, if snip is not in pkt.

Definition at line 135 of file pkt.h.

◆ gnrc_pktsnip_search_type()

gnrc_pktsnip_t* gnrc_pktsnip_search_type ( gnrc_pktsnip_t pkt,
gnrc_nettype_t  type 
)

Searches the packet for a packet snip of a specific type.

Parameters
[in]pktlist of packet snips
[in]typethe type to search for
Returns
the packet snip in pkt with gnrc_nettype_t type
NULL, if none of the snips in pkt is of type