-
Notifications
You must be signed in to change notification settings - Fork 2k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
sock: Introduction of new application layer API #5758
Changes from all commits
7ef177a
b71c2f3
44af876
6f06def
01b0975
b24d9de
bb7736a
a4fd05c
278f046
a41bc13
1f74eae
877cad9
26ee724
777c8f7
002be06
ce205af
73861e2
d17ef91
09703e1
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,209 @@ | ||
/* | ||
* Copyright (C) 2016 Alexander Aring <aar@pengutronix.de> | ||
* Freie Universität Berlin | ||
* HAW Hamburg | ||
* Kaspar Schleiser <kaspar@schleiser.de> | ||
* | ||
* 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 minimal common API for applications to connect to the | ||
* different network stacks | ||
* | ||
* About | ||
* ===== | ||
* | ||
* ~~~~~~~~~~~~~~~~~~~~ | ||
* +---------------+ | ||
* | Application | | ||
* +---------------+ | ||
* ^ | ||
* | | ||
* v | ||
* sock | ||
* ^ | ||
* | | ||
* v | ||
* +---------------+ | ||
* | Network Stack | | ||
* +---------------+ | ||
* ~~~~~~~~~~~~~~~~~~~~ | ||
* | ||
* This module provides a minimal set of functions to establish connections or | ||
* send and receives datagrams using different types of communication. Together, | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
"differnet types of communication"? please rephrase |
||
* they serve as a common API that connects application- and network stack code. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
|
||
* | ||
* 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 | ||
* | ||
* Each network stack must implement at least one sock type. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I think you can drop this. |
||
* | ||
* Note that there might be no relation between the different sock types. | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. what does that mean? |
||
* For simplicity and modularity this API doesn't put any restriction of the | ||
* actual implementation of the type. For example, one implementation might | ||
* choose to have all sock types have 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. | ||
* | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The whole paragraph should go way down into a section called sth like "implementor notes". |
||
* How To Use | ||
* ========== | ||
* | ||
* A RIOT application uses the functions provided by one or more of the | ||
* sock type headers (for example @ref sock_udp), 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) | ||
* | ||
* 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. | ||
* | ||
* @author Alexander Aring <aar@pengutronix.de> | ||
* @author Simon Brummer <simon.brummer@haw-hamburg.de> | ||
* @author Cenk Gündoğan <mail@cgundogan.de> | ||
* @author Peter Kietzmann <peter.kietzmann@haw-hamburg.de> | ||
* @author Martine Lenders <m.lenders@fu-berlin.de> | ||
* @author Kaspar Schleiser <kaspar@schleiser.de> | ||
* | ||
* @{ | ||
* | ||
* @file | ||
* @brief Common sock API definitions | ||
* | ||
* @author Martine Lenders <m.lenders@fu-berlin.de> | ||
* @author Kaspar Schleiser <kaspar@schleiser.de> | ||
*/ | ||
|
||
#ifndef NET_SOCK_H_ | ||
#define NET_SOCK_H_ | ||
|
||
#include <stdint.h> | ||
|
||
#ifdef __cplusplus | ||
extern "C" { | ||
#endif | ||
|
||
#if defined(DOXYGEN) | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 👍 There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I did not follow the whole discussion, but why is the activation of There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. So it appears in the documentation (the actual activation is done by the stack if it supports it). There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Hmm, but I am still wondering, why it is not necessary to There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. I don't understand what you mean? If the implementation does not has IPv6 support (or the user choose to not use IPv6 if there is an alternative), why would it be necessary to define it? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. If there is confusion about the semantics of this macro (activate IPv6 support for sock, as documented), then please state this so I can adapt the documentation accordingly. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. OK I understand now. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yes! |
||
/** | ||
* @brief compile flag to activate IPv6 support for sock | ||
*/ | ||
#define SOCK_HAS_IPV6 | ||
#endif | ||
|
||
/** | ||
* @brief Common flags for @ref net_conn | ||
* @name 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 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 { | ||
#if defined(SOCK_HAS_IPV6) || defined(DOXYGEN) | ||
/** | ||
* @brief IPv6 address mode | ||
* | ||
* @note only available if @ref SOCK_HAS_IPV6 is defined. | ||
*/ | ||
uint8_t ipv6[16]; | ||
#endif | ||
uint32_t ipv4; /**< IPv4 address mode */ | ||
} 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 { | ||
#if defined(SOCK_HAS_IPV6) || defined(DOXYGEN) | ||
/** | ||
* @brief IPv6 address mode | ||
* | ||
* @note only available if @ref SOCK_HAS_IPV6 is defined. | ||
*/ | ||
uint8_t ipv6[16]; | ||
#endif | ||
uint32_t ipv4; /**< IPv4 address mode */ | ||
} 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 */ | ||
}; | ||
|
||
#ifdef __cplusplus | ||
} | ||
#endif | ||
|
||
#endif /* NET_SOCK_H_ */ | ||
/** @} */ |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't like that tagline.
The API is supposed to be used to write network applications. Would you mind to rephrase?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
If there is so much doc change needed, why did you merge?!?