/* * Copyright (C) 2016 Alexander Aring * Freie Universität Berlin * HAW Hamburg * Kaspar Schleiser * * This file is subject to the terms and conditions of the GNU Lesser * General Public License v2.1. See the file LICENSE in the top level * directory for more details. */ /** * @defgroup net_sock Sock API * @ingroup net * @brief 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: * * * @ref sock_ip_t (net/sock/ip.h): raw IP sock * * @ref sock_tcp_t (net/sock/tcp.h): TCP sock * * @ref 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 @ref 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](net_gnrc) 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 * @author Simon Brummer * @author Cenk Gündoğan * @author Peter Kietzmann * @author Martine Lenders * @author Kaspar Schleiser * * @{ * * @file * @brief Common sock API definitions * * @author Martine Lenders * @author Kaspar Schleiser */ #ifndef NET_SOCK_H_ #define NET_SOCK_H_ #include #ifdef __cplusplus extern "C" { #endif #if defined(DOXYGEN) /** * @name Compile flags * @brief Flags to (de)activate certain functionalities * @{ */ #define SOCK_HAS_IPV6 /**< activate IPv6 support */ /** @} */ #endif /** * @name Sock flags * @brief Common flags for @ref net_sock * @anchor net_sock_flags * @{ */ #define SOCK_FLAGS_REUSE_EP (0x0001) /**< allow to reuse end point on bind */ /** @} */ /** * @brief Special netif ID for "any interface" * @todo Use an equivalent defintion from PR #5511 */ #define SOCK_ADDR_ANY_NETIF (0) /** * @brief Address to bind to any IPv4 address */ #define SOCK_IPV4_EP_ANY { .family = AF_INET, \ .netif = SOCK_ADDR_ANY_NETIF } #if defined(SOCK_HAS_IPV6) || defined(DOXYGEN) /** * @brief Address to bind to any IPv6 address */ #define SOCK_IPV6_EP_ANY { .family = AF_INET6, \ .netif = SOCK_ADDR_ANY_NETIF } #endif /** * @brief Special value meaning "wait forever" (don't timeout) */ #define SOCK_NO_TIMEOUT (UINT32_MAX) /** * @brief Abstract IP end point and end point for a raw IP sock object */ typedef struct { /** * @brief family of sock_ip_ep_t::addr * * @see @ref net_af */ int family; union { #ifdef SOCK_HAS_IPV6 /** * @brief IPv6 address mode * * @note only available if @ref SOCK_HAS_IPV6 is defined. */ uint8_t ipv6[16]; #endif uint8_t ipv4[4]; /**< IPv4 address mode */ uint32_t ipv4_u32; /**< IPv4 address *in network byte order* */ } addr; /**< address */ /** * @brief stack-specific network interface ID * * @todo port to common network interface identifiers in PR #5511. * * Use @ref 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 netif; } sock_ip_ep_t; /** * @brief Common IP-based transport layer end point */ struct _sock_tl_ep { /** * @brief family of sock_ip_ep_t::addr * * @see @ref net_af */ int family; union { #ifdef SOCK_HAS_IPV6 /** * @brief IPv6 address mode * * @note only available if @ref SOCK_HAS_IPV6 is defined. */ uint8_t ipv6[16]; #endif uint8_t ipv4[4]; /**< IPv4 address mode */ uint32_t ipv4_u32; /**< IPv4 address *in network byte order* */ } addr; /**< address */ /** * @brief stack-specific network interface ID * * @todo port to common network interface identifiers in PR #5511. * * Use @ref 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 netif; uint16_t port; /**< transport layer port (in host byte order) */ }; #ifdef __cplusplus } #endif #endif /* NET_SOCK_H_ */ /** @} */