Diff: features/netsocket/TLSSocketWrapper.h

Revision:

1:9db0e321a9f4

Parent:

0:5b88d5760320

--- a/features/netsocket/TLSSocketWrapper.h	Tue Dec 17 23:23:45 2019 +0000
+++ b/features/netsocket/TLSSocketWrapper.h	Tue Dec 31 06:02:27 2019 +0000
@@ -81,7 +81,9 @@
      *
      * @param root_ca Root CA Certificate in any Mbed TLS-supported format.
      * @param len     Length of certificate (including terminating 0 for PEM).
-     * @return        0 on success, negative error code on failure.
+     * @retval NSAPI_ERROR_OK on success.
+     * @retval NSAPI_ERROR_NO_MEMORY in case there is not enough memory to allocate certificate.
+     * @retval NSAPI_ERROR_PARAMETER in case the provided root_ca parameter failed parsing.
      */
     nsapi_error_t set_root_ca_cert(const void *root_ca, size_t len);
 
@@ -90,6 +92,9 @@
      * @note Must be called before calling connect()
      *
      * @param root_ca_pem Root CA Certificate in PEM format.
+     * @retval NSAPI_ERROR_OK on success.
+     * @retval NSAPI_ERROR_NO_MEMORY in case there is not enough memory to allocate certificate.
+     * @retval NSAPI_ERROR_PARAMETER in case the provided root_ca parameter failed parsing.
      */
     nsapi_error_t set_root_ca_cert(const char *root_ca_pem);
 
@@ -99,7 +104,8 @@
      * @param client_cert_len Certificate size including the terminating null byte for PEM data.
      * @param client_private_key_pem Client private key in PEM or DER format.
      * @param client_private_key_len Key size including the terminating null byte for PEM data
-     * @return   0 on success, negative error code on failure.
+     * @retval NSAPI_ERROR_OK on success.
+     * @retval NSAPI_ERROR_PARAMETER in case the provided root_ca parameter failed parsing.
      */
     nsapi_error_t set_client_cert_key(const void *client_cert, size_t client_cert_len,
                                       const void *client_private_key_pem, size_t client_private_key_len);
@@ -108,7 +114,8 @@
      *
      * @param client_cert_pem Client certification in PEM format.
      * @param client_private_key_pem Client private key in PEM format.
-     * @return   0 on success, negative error code on failure.
+     * @retval NSAPI_ERROR_OK on success.
+     * @retval NSAPI_ERROR_PARAMETER in case the provided root_ca parameter failed parsing.
      */
     nsapi_error_t set_client_cert_key(const char *client_cert_pem, const char *client_private_key_pem);
 
@@ -119,7 +126,12 @@
      *
      *  @param data     Buffer of data to send to the host.
      *  @param size     Size of the buffer in bytes.
-     *  @return         Number of sent bytes on success, negative error code on failure.
+     *  @retval         int Number of sent bytes on success
+     *  @retval         NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
+     *  @retval         NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
+     *                  and send cannot be performed immediately.
+     *  @retval         NSAPI_ERROR_DEVICE_ERROR in case of tls-related errors.
+     *                  See @ref mbedtls_ssl_write.
      */
     virtual nsapi_error_t send(const void *data, nsapi_size_t size);
 
@@ -130,18 +142,26 @@
      *
      *  @param data     Destination buffer for data received from the host.
      *  @param size     Size of the buffer in bytes.
-     *  @return         Number of received bytes on success, negative error
-     *                  code on failure. If no data is available to be received
-     *                  and the peer has performed an orderly shutdown,
-     *                  recv() returns 0.
+     *  @retval         int Number of sent bytes on success
+     *  @retval         NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
+     *  @retval         NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
+     *                  and send cannot be performed immediately.
+     *  @retval         NSAPI_ERROR_DEVICE_ERROR in case of tls-related errors.
+     *                  See @ref mbedtls_ssl_read.
+     *  @return         0 if no data is available to be received
+     *                  and the peer has performed an orderly shutdown.
      */
     virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size);
 
     /* = Functions inherited from Socket = */
     virtual nsapi_error_t close();
-    /*
+    /**
+     *  Connect the transport socket and start handshake.
+     *
      *  @note: In case connect() returns an error, the state of the socket is
      *  unspecified. A new socket should be created before reconnecting.
+     *
+     *  See @ref Socket::connect and @ref start_handshake
      */
     virtual nsapi_error_t connect(const SocketAddress &address = SocketAddress());
     virtual nsapi_size_or_error_t sendto(const SocketAddress &address, const void *data, nsapi_size_t size);
@@ -217,7 +237,11 @@
      *  does not happen twice.
      *
      *  @param        first_call is this a first call to Socket::connect() API.
-     *  @return       0 on success, negative error code on failure
+     *  @retval       NSAPI_ERROR_OK if we happen to complete the request on the first call.
+     *  @retval       NSAPI_ERROR_IN_PROGRESS if the first call did not complete the request.
+     *  @retval       NSAPI_ERROR_NO_SOCKET in case the transport socket was not created correctly.
+     *  @retval       NSAPI_ERROR_AUTH_FAILURE in case of tls-related authentication errors.
+     *                See @ref mbedtls_ctr_drbg_seed, @ref mbedtls_ssl_setup. @ref mbedtls_ssl_handshake.
      */
     nsapi_error_t start_handshake(bool first_call);