Sock API

Provides a network API for applications and library. More...

Detailed Description

Provides a network API for applications and library.

About

+---------------+
| Application |
+---------------+
^
|
v
sock
^
|
v
+---------------+
| Network Stack |
+---------------+

This module provides a set of functions to establish connections or send and receive datagrams using different types of protocols. Together, they serve as an API that allows an application or library to connect to a network.

It was designed with the following priorities in mind

  1. No need for dynamic memory allocation
  2. User friendliness
  3. Simplicity
  4. Efficiency (at both front- and backend)
  5. Portability

Currently the following sock types are defined:

Note that there might be no relation between the different sock types. So casting e.g. sock_ip_t to sock_udp_t might not be as straight forward, as you think depending on the networking architecture.

How To Use

A RIOT application uses the functions provided by one or more of the sock type headers (for example sock_udp_t), regardless of the network stack it uses. The network stack used under the bonnet is specified by including the appropriate module (for example USEMODULE += gnrc_sock_udp for GNRC's version of this API).

This allows for network stack agnostic code on the application layer. The application code to establish a connection is always the same, allowing the network stack underneath to be switched simply by changing the USEMODULE definitions in the application's Makefile.

The actual code very much depends on the used sock type. Please refer to their documentation for specific examples.

Implementor Notes

Type definition

For simplicity and modularity this API doesn't put any restriction on the actual implementation of the type. For example, one implementation might choose to have all sock types having a common base class or use the raw IP sock type to send e.g. UDP packets, while others will keep them completely separate from each other.

Author
Alexander Aring aar@p.nosp@m.engu.nosp@m.troni.nosp@m.x.de
Simon Brummer simon.nosp@m..bru.nosp@m.mmer@.nosp@m.haw-.nosp@m.hambu.nosp@m.rg.d.nosp@m.e
Cenk Gündoğan mail@.nosp@m.cgun.nosp@m.dogan.nosp@m..de
Peter Kietzmann peter.nosp@m..kie.nosp@m.tzman.nosp@m.n@ha.nosp@m.w-ham.nosp@m.burg.nosp@m..de
Martine Lenders m.len.nosp@m.ders.nosp@m.@fu-b.nosp@m.erli.nosp@m.n.de
Kaspar Schleiser kaspa.nosp@m.r@sc.nosp@m.hleis.nosp@m.er.d.nosp@m.e

Modules

 Asynchronous sock with event API
 Provides an implementation of asynchronous sock for Event Queue.
 
 DNS sock API
 Sock DNS client.
 
 DTLS sock API
 Sock submodule for DTLS.
 
 Raw IPv4/IPv6 sock API
 Sock submodule for raw IPv4/IPv6.
 
 Sock extension for asynchronous access
 Provides backend functionality for asynchronous sock access.
 
 TCP sock API
 Sock submodule for TCP.
 
 UDP sock API
 Sock submodule for UDP.
 
 sock utility functions
 sock utility function
 

Files

file  sock.h
 Common sock API definitions.
 

Data Structures

struct  sock_ip_ep_t
 Abstract IP end point and end point for a raw IP sock object. More...
 
struct  _sock_tl_ep
 Common IP-based transport layer end point. More...
 

Macros

#define SOCK_ADDR_ANY_NETIF   (0)
 Special netif ID for "any interface". More...
 
#define SOCK_IPV4_EP_ANY
 Address to bind to any IPv4 address. More...
 
#define SOCK_IPV6_EP_ANY
 Address to bind to any IPv6 address. More...
 
#define SOCK_NO_TIMEOUT   (UINT32_MAX)
 Special value meaning "wait forever" (don't timeout)
 

Typedefs

typedef uint8_t sock_aux_flags_t
 Type holding the flags used to request specific auxiliary data. More...
 

Enumerations

enum  { SOCK_AUX_GET_LOCAL = (1LU << 0), SOCK_AUX_GET_TIMESTAMP = (1LU << 1) }
 Flags used to request auxiliary data. More...
 

Compile flags

Flags to (de)activate certain functionalities

#define SOCK_HAS_IPV6
 activate IPv6 support
 
#define SOCK_HAS_ASYNC
 activate asynchronous event functionality More...
 
#define SOCK_HAS_ASYNC_CTX
 Activate context for asynchronous events. More...
 

Sock flags

Common flags for Sock API

#define SOCK_FLAGS_REUSE_EP   (0x0001)
 allow to reuse end point on bind
 

Macro Definition Documentation

◆ SOCK_ADDR_ANY_NETIF

#define SOCK_ADDR_ANY_NETIF   (0)

Special netif ID for "any interface".

Todo:
Use an equivalent definition from PR #5511

Definition at line 152 of file sock.h.

◆ SOCK_HAS_ASYNC

#define SOCK_HAS_ASYNC

activate asynchronous event functionality

See also
Sock extension for asynchronous access

Definition at line 123 of file sock.h.

◆ SOCK_HAS_ASYNC_CTX

#define SOCK_HAS_ASYNC_CTX

Activate context for asynchronous events.

See also
Sock extension for asynchronous access

This can be used if an asynchronous mechanism needs context (e.g. an event instance for an event loop). An event handling implementation then needs to provide a sock_async_ctx.h header file containing a definition for the sock_async_ctx_t type.

Definition at line 134 of file sock.h.

◆ SOCK_IPV4_EP_ANY

#define SOCK_IPV4_EP_ANY
Value:
{ .family = AF_INET, \
internetwork address family: UDP, TCP, etc.
Definition: af.h:36
#define SOCK_ADDR_ANY_NETIF
Special netif ID for "any interface".
Definition: sock.h:152

Address to bind to any IPv4 address.

Definition at line 157 of file sock.h.

◆ SOCK_IPV6_EP_ANY

#define SOCK_IPV6_EP_ANY
Value:
{ .family = AF_INET6, \
internetwork address family with IPv6: UDP, TCP, etc.
Definition: af.h:38
#define SOCK_ADDR_ANY_NETIF
Special netif ID for "any interface".
Definition: sock.h:152

Address to bind to any IPv6 address.

Definition at line 164 of file sock.h.

Typedef Documentation

◆ sock_aux_flags_t

typedef uint8_t sock_aux_flags_t

Type holding the flags used to request specific auxiliary data.

This is a bitmask of SOCK_AUX_GET_..., e.g. if the mask contains SOCK_AUX_GET_LOCAL, the local address/endpoint is requested

The underlying type can be changed without further notice, if more flags are needed. Thus, only the typedefed type should be used to store the flags.

Definition at line 301 of file sock.h.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Flags used to request auxiliary data.

Enumerator
SOCK_AUX_GET_LOCAL 

Flag to request the local address/endpoint.

Note
Select module sock_aux_local and a compatible network stack to use this

This is the address/endpoint the packet/datagram/segment was received on. This flag will be cleared if the network stack stored the local address/endpoint as requested, otherwise the bit remains set.

Depending on the family of the socket, the timestamp will be stored in sock_udp_aux_rx_t::local, sock_ip_aux_rx_t::local, or in sock_dtls_aux_rx_t::local.

SOCK_AUX_GET_TIMESTAMP 

Flag to request the time stamp of transmission / reception.

Note
Select module sock_aux_timestamp and a compatible network stack to use this

Unless otherwise noted, the time stamp is the current system time in nanoseconds on which the start of frame delimiter or preamble was sent / received.

Set this flag in the auxiliary data structure prior to the call of sock_udp_recv_aux / sock_udp_send_aux / sock_ip_recv_aux / etc. to request the time stamp of reception / transmission. This flag will be cleared if the timestamp was stored, otherwise it remains set.

Depending on the family of the socket, the timestamp will be stored in for reception in sock_udp_aux_rx_t::timestamp, sock_ip_aux_rx_t::timestamp, or sock_dtls_aux_rx_t::timestamp. For transmission it will be stored in sock_udp_aux_tx_t::timestamp, sock_ip_aux_tx_t::timestamp, or sock_dtls_aux_tx_t::timestamp.

Definition at line 251 of file sock.h.