- Generated on Fri Nov 15 2024 13:54:48 by
1.9.8
Provides a network API for applications and library. More...
Provides a network API for applications and library.
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
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.
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.
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.
Modules | |
| Asynchronous sock with event API | |
| Provides an implementation of asynchronous sock for Event Queue. | |
| DNS over DTLS sock API | |
| Sock DNS over DTLS client. | |
| 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". | |
| #define | SOCK_IPV4_EP_ANY |
| Address to bind to any IPv4 address. | |
| #define | SOCK_IPV6_EP_ANY |
| Address to bind to any IPv6 address. | |
| #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. | |
Enumerations | |
| enum | { SOCK_AUX_GET_LOCAL = (1LU << 0) , SOCK_AUX_GET_TIMESTAMP = (1LU << 1) , SOCK_AUX_GET_RSSI = (1LU << 2) , SOCK_AUX_SET_LOCAL = (1LU << 3) , SOCK_AUX_GET_TTL = (1LU << 4) } |
| 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 | |
| #define | SOCK_HAS_ASYNC_CTX |
| Activate context for asynchronous events. | |
Sock flags | |
Common flags for Sock API | |
| #define | SOCK_FLAGS_REUSE_EP (0x0001) |
| allow to reuse end point on bind | |
| #define | SOCK_FLAGS_CONNECT_REMOTE (0x0002) |
| restrict responses to remote address | |
| #define SOCK_ADDR_ANY_NETIF (0) |
| #define SOCK_FLAGS_CONNECT_REMOTE (0x0002) |
| #define SOCK_FLAGS_REUSE_EP (0x0001) |
| #define SOCK_HAS_ASYNC |
activate asynchronous event functionality
| #define SOCK_HAS_ASYNC_CTX |
Activate context for asynchronous events.
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.
| #define SOCK_IPV4_EP_ANY |
Address to bind to any IPv4 address.
| #define SOCK_IPV6_EP_ANY |
| #define SOCK_NO_TIMEOUT (UINT32_MAX) |
| 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.
| anonymous enum |
Flags used to request auxiliary data.
| Enumerator | |
|---|---|
| SOCK_AUX_GET_LOCAL | Flag to request the local address/endpoint.
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.
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. |
| SOCK_AUX_GET_RSSI | Flag to request the RSSI value of received frame.
Set this flag in the auxiliary data structure prior to the call of sock_udp_recv_aux / sock_ip_recv_aux / etc. to request the RSSI value of a received frame. This flag will be cleared if the timestamp was stored, otherwise it remains set. Depending on the family of the socket, the RSSI value will be stored in sock_udp_aux_rx_t::rssi, sock_ip_aux_rx_t::rssi, or sock_dtls_aux_rx_t::rssi. |
| SOCK_AUX_SET_LOCAL | Flag to set the local address/endpoint.
This is the address/endpoint the packet/datagram/segment will be sent from. 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_tx_t::local, sock_ip_aux_tx_t::local, or in sock_dtls_aux_tx_t::local. |
| SOCK_AUX_GET_TTL | Flag to request the TTL value of received frame.
Set this flag in the auxiliary data structure prior to the call of sock_udp_recv_aux / sock_ip_recv_aux / etc. to request the TTL value of a received frame. This flag will be cleared if the time to live was stored, otherwise it remains set. Depending on the family of the socket, the TTL value will be stored in sock_udp_aux_rx_t::ttl or sock_dtls_aux_rx_t::ttl. |
1.9.8