Sock API¶
Provides a network API for applications and library.
About¶
1 2 3 4 5 6 7 8 9 10 11 12 13 | +---------------+
| 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
- No need for dynamic memory allocation
- User friendliness
- Simplicity
- Efficiency (at both front- and backend)
- Portability
Currently the following sock
types are defined:
ip.h::sock_ip_t
(net/sock/ip.h): raw IP socksock/tcp.h::sock_tcp_t
(net/sock/tcp.h): TCP socksock/udp.h::sock_udp_t
(net/sock/udp.h): UDP sock
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.h::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.
-
SOCK_HAS_IPV6
¶ activate IPv6 support
-
SOCK_FLAGS_REUSE_EP
¶ allow to reuse end point on bind
1
(0x0001)
-
SOCK_ADDR_ANY_NETIF
¶ Special netif ID for “any interface”.
1
(0)
Use an equivalent defintion from PR #5511
-
SOCK_IPV4_EP_ANY
¶ Address to bind to any IPv4 address.
1 2
{ .family = AF_INET, \ .netif = SOCK_ADDR_ANY_NETIF }
-
SOCK_IPV6_EP_ANY
¶ Address to bind to any IPv6 address.
1 2
{ .family = AF_INET6, \ .netif = SOCK_ADDR_ANY_NETIF }
-
SOCK_NO_TIMEOUT
¶ Special value meaning “wait forever” (don’t timeout)
1
(UINT32_MAX)
-
struct
sock_ip_ep_t
¶ Abstract IP end point and end point for a raw IP sock object.
-
int
family
¶ family of
sock.h::sock_ip_ep_t::addr
See also
-
uint8_t
ipv6
()¶ IPv6 address mode.
Note
only available if
sock.h::SOCK_HAS_IPV6
is defined.
-
uint8_t
ipv4
()¶ IPv4 address mode.
-
uint32_t
ipv4_u32
¶ IPv4 address in network byte order
-
union sock_ip_ep_t::@198
addr
¶ address
-
uint16_t
netif
¶ stack-specific network interface ID
port to common network interface identifiers in PR #5511.
Use
sock.h::SOCK_ADDR_ANY_NETIF
for any interface. For reception this is the local interface the message came over, for transmission, this is the local interface the message should be send over
-
int
-
struct
_sock_tl_ep
¶ Common IP-based transport layer end point.
-
int
family
¶ family of
sock.h::sock_ip_ep_t::addr
See also
-
uint8_t
ipv6
()¶ IPv6 address mode.
Note
only available if
sock.h::SOCK_HAS_IPV6
is defined.
-
uint8_t
ipv4
()¶ IPv4 address mode.
-
uint32_t
ipv4_u32
¶ IPv4 address in network byte order
-
union _sock_tl_ep::@199
addr
¶ address
-
uint16_t
netif
¶ stack-specific network interface ID
port to common network interface identifiers in PR #5511.
Use
sock.h::SOCK_ADDR_ANY_NETIF
for any interface. For reception this is the local interface the message came over, for transmission, this is the local interface the message should be send over
-
uint16_t
port
¶ transport layer port (in host byte order)
-
int