Packet

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_t *	gnrc_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_t *	gnrc_pkt_append (gnrc_pktsnip_t *pkt, gnrc_pktsnip_t *snip)
	Appends a snip to a packet. More...
static gnrc_pktsnip_t *	gnrc_pkt_prepend (gnrc_pktsnip_t *pkt, gnrc_pktsnip_t *snip)
	Prepends a snip to a packet. More...
static gnrc_pktsnip_t *	gnrc_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_t *	gnrc_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]	pkt	A packet.
[in]	snip	A snip.

Returns

The new head of pkt.

Definition at line 172 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]

pkt

first snip in the packet

Returns

number of snips in the given packet

Definition at line 268 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]	pkt	A packet.
[in]	snip	A snip.

Returns

The new head of pkt.

Definition at line 211 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]

pkt

list of packet snips.

Returns

length of the list of headers.

Definition at line 152 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]	pkt	list of packet snips.
[in]	type	type of snip to stop calculation.

Returns

length of the list of headers.

Definition at line 244 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]	pkt	A packet.
[in]	snip	A snip.

Returns

The new head of pkt.

Definition at line 196 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]	pkt	A packet.
[in]	snip	The 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 136 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]	pkt	list of packet snips
[in]	type	the 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