[riot-notifications] [RIOT-OS/RIOT] sock_dtls: add timeout to sock_dtls_send and sock_dtls_session_create (#14043)

Martine Lenders notifications at github.com
Thu May 14 17:10:45 CEST 2020


@miri64 requested changes on this pull request.

> sock_dtls: fix doxygen warnings

That commit does not contain any doxygen warning fixes, but mostly style fixes (btw, its ok, if a line is >80, as long as it stays <100)

> - * @return  -EADDRNOTAVAIL, if the local endpoint of @p sock is not set.
- * @return  -EINVAL, if @p remote is invalid or @p sock is not properly
- *          initialized (or closed while sock_udp_recv() blocks).

Shouldn't those two still be relevant for the new behavior?

>   *
- * @note Function may block until a session is created if there is no
- *       existing session with @p remote.
- *
- * @note Initiating a session through this function will require
- * @ref sock_dtls_recv() called from another thread to receive the handshake
- * messages.
+ * @note    When blocking, we will need an extra thread to call the receive

```suggestion
 * @note    When blocking, we will need an extra thread to call the `sock_dtls_recv()`
```

>   *   3. Start listening with @ref sock_dtls_recv()
  * - Client operation
  *   1. Create UDP sock @ref sock_udp_create()
- *   2. Create DTLS sock @ref sock_dtls_create() using role @ref SOCK_DTLS_CLIENT
- *   3. Create session to server @ref sock_dtls_session_create()
+ *   2. Create DTLS sock @ref sock_dtls_create() using role
+ *      @ref SOCK_DTLS_CLIENT
+ *   3. Start handshake session to server @ref sock_dtls_session_init()
+ *   4. Handle incoming handshake packets with @ref sock_dtls_session_recv()

```suggestion
 *   4. Handle incoming handshake packets with @ref sock_dtls_recv()
```

> @@ -694,6 +711,46 @@ ssize_t sock_dtls_send(sock_dtls_t *sock, sock_dtls_session_t *remote,
  */
 void sock_dtls_close(sock_dtls_t *sock);
 
+/**
+ * @brief Creates a new DTLS session
+ *
+ * Sends a ClientHello to initiate a handshake process with a DTLS server  at

```suggestion
 * Sends a ClientHello message to initiate a handshake process with a DTLS server  at
```
?

> @@ -547,25 +567,18 @@ int sock_dtls_create(sock_dtls_t *sock, sock_udp_t *udp_sock,
                      credman_tag_t tag, unsigned version, unsigned role);
 
 /**
- * @brief Creates a new DTLS session
- *
- * Initializes handshake process with a DTLS server  at @p ep.
+ * @brief Send a ClientHello to start the handshake

```suggestion
 * @brief Send a ClientHello message to start the handshake
```

However, I would prefer to keep it abstract in the `@brief`:

```
Initialize session handshake.
```

It should also be explained in the detailed section of this function, that `sock_dtls_recv()` must be called to finish the handshake.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/RIOT-OS/RIOT/pull/14043#pullrequestreview-411897404
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.riot-os.org/pipermail/notifications/attachments/20200514/d6b4b5ab/attachment.htm>


More information about the notifications mailing list