fixup! conn: Simplify and overhaul conn API

[ci skip]

[ci skip]

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;
 
 /**

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
 }

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,30 +102,30 @@ 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)`
  *
  * @param[in] conn  A TCP connectivity object.
  * @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);