diff --git a/sys/include/net/conn/ep.h b/sys/include/net/conn/ep.h index 223d5ab76103..a5c7d98d943f 100644 --- a/sys/include/net/conn/ep.h +++ b/sys/include/net/conn/ep.h @@ -50,7 +50,6 @@ typedef struct { * over */ uint16_t netif; - uint8_t proto; /**< protocol for the IPv4/IPv6 end point */ } conn_ep_ip_t; /** diff --git a/sys/include/net/conn/ip.h b/sys/include/net/conn/ip.h index 3cb12b5bfd78..c642959d634e 100644 --- a/sys/include/net/conn/ip.h +++ b/sys/include/net/conn/ip.h @@ -69,7 +69,15 @@ typedef void (*conn_ip_recv_cb_t)(conn_ip_t *conn); * stack-specific connectivity descriptor. * @param[in] src Local end point for the connectivity object. * May be NULL to solicit implicit bind on - * @ref conn_ip_send() + * @ref conn_ip_sendto() and @ref conn_ip_send(). + * @param[in] dst Remote end point for the connectivity object. + * May be `NULL` but then the `dst` parameter of + * @ref conn_ip_sendto() may not be `NULL` and + * @ref conn_ip_send() will always error with return value + * -ENOTCONN. conn_ep_ip_t::port may not be 0 if `dst != NULL`. + * @param[in] proto Protocol to use in the raw IPv4/IPv6 connectivity object + * (the `protocol` header field in IPv4 and the `next_header` + * field in IPv6). * @param[in] cb Callback called asynchronously, when a packet is received. * May be NULL in which case asynchronous reception is not * possible. @@ -78,14 +86,14 @@ typedef void (*conn_ip_recv_cb_t)(conn_ip_t *conn); * @return 0 on success. * @return -EADDRINUSE, if `src != NULL` and the stack reports that @p src is * already use elsewhere - * @return -EAFNOSUPPORT, if `src != NULL` and conn_ep_ip_t::family of @p src - * is not supported. - * @return -EINVAL, if `src != NULL` and conn_ep_ip_t::proto of @p src is not - * supported. - * @return -EPROTONOSUPPORT, if `src != NULL` and conn_ep_ip_t::proto of @p src - * is not supported in conn_ep_ip_t::family of @p src. + * @return -EAFNOSUPPORT, if `src != NULL` or `dst != NULL` and + * conn_ep_ip_t::family of @p src or @p dst is not supported. + * @return -EINVAL, if `proto` is not supported. + * @return -EPROTONOSUPPORT, if `src != NULL` or `dst != NULL` and + * proto is not supported by conn_ep_ip_t::family of @p src or @p dst. */ int conn_ip_create(conn_ip_t *conn, const conn_ep_ip_t *src, + const conn_ep_ip_t *dst, uint8_t proto, conn_ip_recv_cb_t cb); /** @@ -111,7 +119,20 @@ void conn_ip_close(conn_ip_t *conn); int conn_ip_get_local(conn_ip_t *conn, conn_ep_ip_t *ep); /** - * @brief Receives a message over IPv4/IPv6 + * @brief Gets the remote end point of a UDP connectivity + * + * @pre `(conn != NULL) && (ep != NULL)` + * + * @param[in] conn A UDP connectivity object. + * @param[out] ep The remote end point. + * + * @return 0 on success. + * @return -ENOTCONN, when @p conn has no remote end point bound to it. + */ +int conn_ip_get_remote(conn_ip_t *conn, conn_ep_ip_t *ep); + +/** + * @brief Receives a message over IPv4/IPv6 from remote end point * * @pre `(data != NULL) && (max_len > 0)` * @@ -121,36 +142,96 @@ int conn_ip_get_local(conn_ip_t *conn, conn_ep_ip_t *ep); * If received data exceeds @p max_len the data is * truncated and the remaining data can be retrieved * later on. - * @param[out] src_ep Remote end point of the received data. + * @param[out] src Remote end point of the received data. * May be NULL, if it is not required by the application. + * @param[in] timeout Timeout for receive in microseconds. + * This value can be ignored (no timeout) if the + * @ref sys_xtimer module is not present and the stack does + * not support timeouts on its own. * * @note Function blocks if no packet is currently waiting. * * @return The number of bytes received on success. * @return 0, if no received data is available, but everything is in order. + * @return -ETIMEDOUT, if @p timeout expired. */ -int conn_ip_recv(conn_ip_t *conn, void *data, size_t max_len, - conn_ep_ip_t *src_ep); +int conn_ip_recvfrom(conn_ip_t *conn, void *data, size_t max_len, + conn_ep_ip_t *src, uint32_t timeout); /** - * @brief Sends a message over IPv4/IPv6 + * @brief Receives a message over IPv4/IPv6 * - * @pre `(data != NULL) && (len > 0) && (dst_ep != NULL)` + * @pre `(data != NULL) && (max_len > 0)` + * + * @param[in] conn A raw IPv4/IPv6 connectivity object. + * @param[out] data Pointer where the received data should be stored. + * @param[in] max_len Maximum space available at @p data. + * If received data exceeds @p max_len the data is + * truncated and the remaining data can be retrieved + * later on. + * @param[in] timeout Timeout for receive in microseconds. + * This value can be ignored (no timeout) if the + * @ref sys_xtimer module is not present and the stack does + * not support timeouts on its own. + * + * @note Function blocks if no packet is currently waiting. + * + * @return The number of bytes received on success. + * @return 0, if no received data is available, but everything is in order. + * @return -ETIMEDOUT, if @p timeout expired. + */ +static inline int conn_ip_recv(conn_ip_t *conn, void *data, size_t max_len, + uint32_t timeout) +{ + return conn_ip_recvfrom(conn, data, max_len, NULL, timeout); +} + +/** + * @brief Sends a message over IPv4/IPv6 to remote end point + * + * @pre `(data != NULL) && (len > 0) && (dst != NULL)` + * + * @param[in] conn A raw IPv4/IPv6 connectivity object. May be NULL. + * A sensible local end point should be selected by the + * stack in that case. + * @param[in] data Pointer where the received data should be stored. + * @param[in] len Maximum space available at @p data. + * @param[in] dst Remote end point for the send data. + * May be `NULL`, if @p conn has a remote end point. + * + * @note Function blocks until packet is handed to the stack. + * + * @return The number of bytes send on success. + * @return -ENOBUFS, if no memory was available to send @p data. + * @return -ENOTCONN, if `dst == NULL`, but @p conn has no remote end point. + */ +int conn_ip_sendto(conn_ip_t *conn, const void *data, size_t len, + conn_ep_ip_t *dst); + + +/** + * @brief Sends a message over IPv4/IPv6 to remote end point + * + * @pre `(data != NULL) && (len > 0) && (dst != NULL)` * * @param[in] conn A raw IPv4/IPv6 connectivity object. May be NULL. * A sensible local end point should be selected by the * stack in that case. * @param[in] data Pointer where the received data should be stored. * @param[in] len Maximum space available at @p data. - * @param[in] dst_ep Remote end point for the send data. + * @param[in] dst Remote end point for the send data. + * May be `NULL`, if @p conn has a remote end point. * * @note Function blocks until packet is handed to the stack. * * @return The number of bytes send on success. * @return -ENOBUFS, if no memory was available to send @p data. + * @return -ENOTCONN, if @p conn has no remote end point. */ -int conn_ip_send(conn_ip_t *conn, const void *data, size_t len, - conn_ep_ip_t *dst_ep); +static inline int conn_ip_send(conn_ip_t *conn, const void *data, size_t len) +{ + return conn_ip_sendto(conn, data, len, NULL) +} #ifdef __cplusplus } diff --git a/sys/include/net/conn/tcp.h b/sys/include/net/conn/tcp.h index c1813769b7f5..4324b328a4b1 100644 --- a/sys/include/net/conn/tcp.h +++ b/sys/include/net/conn/tcp.h @@ -79,7 +79,7 @@ typedef void (*conn_tcp_recv_cb_t)(conn_tcp_t *conn); * @return -EADDRINUSE, if `src != NULL` and the stack reports that @p src is * already use elsewhere * @return -EAFNOSUPPORT, if `src != NULL` or `dst != NULL` and - * conn_ep_udp_t::family of @p src or @p dst is not supported. + * conn_ep_tcp_t::family of @p src or @p dst is not supported. * @return -ECONNREFUSED, if `dst != NULL`, but no-one is listening on this * address. * @return -ENETUNREACH, if `dst != NULL`, but network is not reachable. @@ -102,7 +102,7 @@ int conn_tcp_create(conn_tcp_t *conn, const conn_ep_tcp_t *src, void conn_tcp_close(conn_tcp_t *conn); /** - * @brief Gets the local address of a TCP connection + * @brief Gets the local end point of a TCP connectivity * * @pre `(conn != NULL) && (ep != NULL)` * @@ -110,22 +110,22 @@ void conn_tcp_close(conn_tcp_t *conn); * @param[out] ep The local end point. * * @return 0 on success. - * @return -EADDRNOTAVAIL, when @p conn has no end point bound to it. + * @return -EADDRNOTAVAIL, when @p conn has no local end point. */ int conn_tcp_get_local(conn_tcp_t *conn, conn_ep_tcp_t *ep); /** - * @brief Gets the address of the connected peer of a TCP connection + * @brief Gets the remote end point of a TCP connectivity * * @pre `(conn != NULL) && (ep != NULL)` * * @param[in] conn A TCP connectivity object. - * @param[out] ep The peer's end point. + * @param[out] ep The remote end point. * * @return 0 on success. - * @return -ENOTCONN, when @p conn is not connected to a peer. + * @return -ENOTCONN, when @p conn is not connected to a remote end point. */ -int conn_tcp_get_peer(conn_tcp_t *conn, conn_ep_tcp_t *ep); +int conn_tcp_get_remote(conn_tcp_t *conn, conn_ep_tcp_t *ep); /** * @brief Receives and handles TCP connection requests from other peers @@ -158,15 +158,22 @@ int conn_tcp_accept(conn_tcp_t *conn, conn_tcp_t *out_conn); * If received data exceeds @p max_len the data is * truncated and the remaining data can be retrieved * later on. + * @param[in] timeout Timeout for receive in microseconds. + * This value can be ignored (no timeout) if the + * @ref sys_xtimer module is not present and the stack does + * not support timeouts on its own. * * @note Function may block. * * @return The number of bytes received on success. * @return 0, if no received data is available, but everything is in order. - * @return -ECONNREFUSED, if peer of @p conn refused to allow the connection. - * @return -ENOTCONN, when @p conn is not connected to a peer. + * @return -ECONNREFUSED, if remote end point of @p conn refused to allow the + * connection. + * @return -ENOTCONN, when @p conn is not connected to a remote end point. + * @return -ETIMEDOUT, if @p timeout expired. */ -int conn_tcp_recv(conn_tcp_t *conn, void *data, size_t max_len); +int conn_tcp_recv(conn_tcp_t *conn, void *data, size_t max_len, + uint32_t timeout); /** * @brief Sends a TCP message @@ -180,9 +187,9 @@ int conn_tcp_recv(conn_tcp_t *conn, void *data, size_t max_len); * @note Function may block. * * @return The number of bytes send on success. - * @return -ECONNRESET, if connection was reset by peer. + * @return -ECONNRESET, if connection was reset by remote end point. * @return -ENOBUFS, if no memory was available to send @p data. - * @return -ENOTCONN, if @p conn is not connected to a peer. + * @return -ENOTCONN, if @p conn is not connected to a remote end point. */ int conn_tcp_send(conn_tcp_t *conn, const void *data, size_t len); diff --git a/sys/include/net/conn/udp.h b/sys/include/net/conn/udp.h index 5d54ca4edd67..4656e163e7e8 100644 --- a/sys/include/net/conn/udp.h +++ b/sys/include/net/conn/udp.h @@ -69,26 +69,32 @@ typedef void (*conn_udp_recv_cb_t)(conn_udp_t *conn); * * @pre `(conn != NULL)` * @pre `(src == NULL) || (src->port != 0)` + * @pre `(dst == NULL) || (dst->port != 0)` * * @param[out] conn Preallocated connectivity object. Must fill the size of the * stack-specific connectivity desriptor. - * @param[in] src point for the connectivity object. - * May be NULL to solicit implicit bind on - * @ref conn_udp_send(). - * conn_ep_udp_t::port may not be 0 if src != NULL + * @param[in] src Local end point for the connectivity object. + * May be `NULL` to solicit implicit bind on + * @ref conn_udp_sendto() and @ref conn_udp_send(). + * conn_ep_udp_t::port may not be 0 if `src != NULL` + * @param[in] dst Remote end point for the connectivity object. + * May be `NULL` but then the `dst` parameter of + * @ref conn_udp_sendto() may not be `NULL` and + * @ref conn_udp_send() will always error with return value + * -ENOTCONN. conn_ep_udp_t::port may not be 0 if `dst != NULL`. * @param[in] cb Callback called asynchronously, when a packet is received. - * May be NULL in which case asynchronous reception is not + * May be `NULL` in which case asynchronous reception is not * possible. * Only is used when the macro `CONN_HAS_CALLBACKS` if defined. * * @return 0 on success. * @return -EADDRINUSE, if `src != NULL` and the stack reports that @p src is * already use elsewhere - * @return -EAFNOSUPPORT, if `src != NULL` and conn_ep_udp_t::family of @p src - * is not supported. + * @return -EAFNOSUPPORT, if `src != NULL` or `dst != NULL` and + * conn_ep_udp_t::family of @p src or @p dst is not supported. */ int conn_udp_create(conn_udp_t *conn, const conn_ep_udp_t *src, - conn_udp_recv_cb_t cb); + conn_ep_udp_t *dst, conn_udp_recv_cb_t cb); /** * @brief Closes a UDP connectivity @@ -100,7 +106,7 @@ int conn_udp_create(conn_udp_t *conn, const conn_ep_udp_t *src, void conn_udp_close(conn_udp_t *conn); /** - * @brief Gets the end point of a UDP connectivity + * @brief Gets the local end point of a UDP connectivity * * @pre `(conn != NULL) && (ep != NULL)` * @@ -108,16 +114,58 @@ void conn_udp_close(conn_udp_t *conn); * @param[out] ep The local end point. * * @return 0 on success. - * @return -EADDRNOTAVAIL, when @p conn has no end point bound to it. + * @return -EADDRNOTAVAIL, when @p conn has no local end point. */ int conn_udp_get_local(conn_udp_t *conn, conn_ep_udp_t *ep); +/** + * @brief Gets the remote end point of a UDP connectivity + * + * @pre `(conn != NULL) && (ep != NULL)` + * + * @param[in] conn A UDP connectivity object. + * @param[out] ep The remote end point. + * + * @return 0 on success. + * @return -ENOTCONN, when @p conn has no remote end point bound to it. + */ +int conn_udp_get_remote(conn_udp_t *conn, conn_ep_udp_t *ep); + +/** + * @brief Receives a UDP message from a remote end point + * + * @pre `(data != NULL) && (max_len > 0)` + * + * @param[in] conn A raw IPv4/IPv6 connectivity object. May be `NULL`. + * A sensible local end point should be selected by the + * stack in that case. + * @param[out] data Pointer where the received data should be stored. + * @param[in] max_len Maximum space available at @p data. + * If received data exceeds @p max_len the data is + * truncated and the remaining data can be retrieved + * later on. + * @param[out] src Remote end point of the received data. + * May be `NULL`, if it is not required by the application. + * @param[in] timeout Timeout for receive in microseconds. + * This value can be ignored (no timeout) if the + * @ref sys_xtimer module is not present and the stack does + * not support timeouts on its own. + * + * @note Function blocks if no packet is currently waiting. + * + * @return The number of bytes received on success. + * @return 0, if no received data is available, but everything is in order. + * @return -ETIMEDOUT, if @p timeout expired. + */ +int conn_udp_recvfrom(conn_udp_t *conn, void *data, size_t max_len, + conn_ep_udp_t *src, uint32_t timeout); + /** * @brief Receives a UDP message * * @pre `(data != NULL) && (max_len > 0)` * - * @param[in] conn A raw IPv4/IPv6 connectivity object. May be NULL. + * @param[in] conn A raw IPv4/IPv6 connectivity object. May be `NULL`. * A sensible local end point should be selected by the * stack in that case. * @param[out] data Pointer where the received data should be stored. @@ -125,36 +173,66 @@ int conn_udp_get_local(conn_udp_t *conn, conn_ep_udp_t *ep); * If received data exceeds @p max_len the data is * truncated and the remaining data can be retrieved * later on. - * @param[out] src_ep Remote end point of the received data. - * May be NULL, if it is not required by the application. + * @param[in] timeout Timeout for receive in microseconds. + * This value can be ignored (no timeout) if the + * @ref sys_xtimer module is not present and the stack does + * not support timeouts on its own. * * @note Function blocks if no packet is currently waiting. * * @return The number of bytes received on success. * @return 0, if no received data is available, but everything is in order. + * @return -ETIMEDOUT, if @p timeout expired. */ -int conn_udp_recv(conn_udp_t *conn, void *data, size_t max_len, - conn_ep_udp_t *src_ep); +static inline int conn_udp_recv(conn_udp_t *conn, void *data, size_t max_len, + uint32_t timeout) +{ + return conn_udp_recvfrom(conn, data, max_len, NULL, timeout); +} + +/** + * @brief Sends a UDP message to remote end point + * + * @pre `(data != NULL) && (len > 0) && (dst != NULL)` + * + * @param[in] conn A raw IPv4/IPv6 connectivity object. May be `NULL`. + * A sensible local end point should be selected by the + * stack in that case. + * @param[in] data Pointer where the received data should be stored. + * @param[in] len Maximum space available at @p data. + * @param[in] dst Remote end point for the send data. + * May be `NULL`, if @p conn has a remote end point. + * + * @note Function blocks until packet is handed to the stack. + * + * @return The number of bytes sent on success. + * @return -ENOBUFS, if no memory was available to send @p data. + * @return -ENOTCONN, if `dst == NULL`, but @p conn has no remote end point. + */ +int conn_udp_sendto(conn_udp_t *conn, const void *data, size_t len, + conn_ep_udp_t *dst); /** * @brief Sends a UDP message * - * @pre `(data != NULL) && (len > 0) && (dst_ep != NULL)` + * @pre `(data != NULL) && (len > 0) && (dst != NULL)` * - * @param[in] conn A raw IPv4/IPv6 connectivity object. May be NULL. + * @param[in] conn A raw IPv4/IPv6 connectivity object. May be `NULL`. * A sensible local end point should be selected by the * stack in that case. * @param[in] data Pointer where the received data should be stored. * @param[in] len Maximum space available at @p data. - * @param[in] dst_ep Remote end point for the send data. * * @note Function blocks until packet is handed to the stack. * * @return The number of bytes sent on success. * @return -ENOBUFS, if no memory was available to send @p data. + * @return -ENOTCONN, if @p conn has no remote end point. */ -int conn_udp_send(conn_udp_t *conn, const void *data, size_t len, - conn_ep_udp_t *dst_ep); +static inline int conn_udp_send(conn_udp_t *conn, const void *data, size_t len) +{ + return conn_udp_sendto(conn, data, len, NULL); +} #ifdef __cplusplus }