Enhance and extend checking of message processing state
- Enhances the documentation of mbedtls_ssl_get_bytes_avail (return
the number of bytes left in the current application data record, if
there is any).
- Introduces a new public function mbedtls_ssl_check_pending for
checking whether any data in the internal buffers still needs to be
processed. This is necessary for users implementing event-driven IO
to decide when they can safely idle until they receive further
events from the underlying transport.
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index cc00070..8b82eff 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -2235,11 +2235,54 @@
#endif /* MBEDTLS_SSL_RENEGOTIATION */
/**
- * \brief Return the number of data bytes available to read
+ * \brief Check if there is data already read from the
+ * underlying transport but not yet processed.
*
* \param ssl SSL context
*
- * \return how many bytes are available in the read buffer
+ * \return 0 if nothing's pending, 1 otherwise.
+ *
+ * \note This function is essential when using the library
+ * with event-driven I/O. The user should not idle
+ * (waiting for events from the underlying transport
+ * or from timers) before this function's check passes.
+ * Otherwise, it's possible to run into a deadlock
+ * (if processing the pending data involves essential
+ * communication with the peer) or to accumulate and
+ * potentially lose data.
+ *
+ * \note This is different in purpose and behaviour from
+ * \c mbedtls_ssl_get_bytes_avail in that it considers
+ * any kind of unprocessed data, not only unread
+ * application data. If \c mbedtls_ssl_get_bytes
+ * returns a non-zero value, this function will
+ * also signal pending data, but the converse does
+ * not hold. For example, in DTLS there might be
+ * further records waiting to be processed from
+ * the current underlying transport's datagram.
+ *
+ * \note If this function returns 0 (data pending), this
+ * does not imply that a subsequent call to
+ * \c mbedtls_ssl_read will provide any data;
+ * e.g., the unprocessed data might turn out
+ * to be an alert or a handshake message.
+ */
+int mbedtls_ssl_check_pending( const mbedtls_ssl_context *ssl );
+
+/**
+ * \brief Return the number of application data bytes
+ * remaining to be read from the current record.
+ *
+ * \param ssl SSL context
+ *
+ * \return How many bytes are available in the application
+ * data record read buffer.
+ *
+ * \note When working over a datagram transport, this is
+ * useful to detect the current datagram's boundary
+ * in case \c mbedtls_ssl_read has written the maximal
+ * amount of data fitting into the input buffer.
+ *
*/
size_t mbedtls_ssl_get_bytes_avail( const mbedtls_ssl_context *ssl );