diff --git a/features/netsocket/DTLSSocket.h b/features/netsocket/DTLSSocket.h index beacc49dd8..ddaf87f961 100644 --- a/features/netsocket/DTLSSocket.h +++ b/features/netsocket/DTLSSocket.h @@ -71,7 +71,8 @@ public: * socket's constructor. * * @param stack Network stack as target for socket. - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. + * See @ref UDPSocket::open. */ virtual nsapi_error_t open(NetworkStack *stack) { @@ -93,7 +94,8 @@ public: * * @param host Hostname of the remote host. * @param port Port of the remote host. - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative error code on failure. + * See @ref TLSSocketWrapper::connect. */ nsapi_error_t connect(const char *host, uint16_t port); diff --git a/features/netsocket/InternetDatagramSocket.h b/features/netsocket/InternetDatagramSocket.h index 75c1223ba8..019a215a91 100644 --- a/features/netsocket/InternetDatagramSocket.h +++ b/features/netsocket/InternetDatagramSocket.h @@ -40,8 +40,12 @@ public: * @param port Port of the remote host. * @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 int Other negative error codes for stack-related failures. + * See @ref NetworkStack::socket_send. */ virtual nsapi_size_or_error_t sendto(const char *host, uint16_t port, const void *data, nsapi_size_t size); @@ -55,8 +59,13 @@ public: * @param address The SocketAddress of the remote host. * @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 NSAPI_ERROR_DNS_FAILURE in case the address parameter cannot + * be resolved. + * @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 int Other negative error codes for stack-related failures. + * See \ref NetworkStack::socket_send. */ virtual nsapi_size_or_error_t sendto(const SocketAddress &address, const void *data, nsapi_size_t size); @@ -77,8 +86,12 @@ public: * @param address Destination for the source address or NULL. * @param data Destination buffer for RAW data to be received from the host. * @param size Size of the buffer in bytes. - * @return Number of received bytes on success, negative error - * code on failure. + * @retval int Number of received 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 int Other negative error codes for stack-related failures. + * See \ref NetworkStack::socket_recv. */ virtual nsapi_size_or_error_t recvfrom(SocketAddress *address, void *data, nsapi_size_t size); @@ -88,7 +101,7 @@ public: * SocketAddress must be in the address parameter. * * @param address The SocketAddress of the remote host. - * @return 0 on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success. */ virtual nsapi_error_t connect(const SocketAddress &address); @@ -102,8 +115,12 @@ public: * * @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 int Other negative error codes for stack-related failures. + * See \ref NetworkStack::socket_send. */ virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size); @@ -119,8 +136,12 @@ public: * * @param data Pointer to 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. + * @retval int Number of received 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 int Other negative error codes for stack-related failures. + * See \ref NetworkStack::socket_recv. */ virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size); diff --git a/features/netsocket/InternetSocket.h b/features/netsocket/InternetSocket.h index 6f1dc3e173..d3ba43664e 100644 --- a/features/netsocket/InternetSocket.h +++ b/features/netsocket/InternetSocket.h @@ -46,7 +46,11 @@ public: * @note Not needed if stack is passed to the socket's constructor. * * @param stack Network stack as target for socket. - * @return 0 on success, negative error code on failure (@see nsapi_types.h). + * @retval NSAPI_ERROR_OK on success. + * @retval NSAPI_ERROR_PARAMETER in case the provided stack was invalid + * or a stack was already created and socket opened successfully. + * @retval int negative error codes for stack-related failures. + * See @ref NetworkStack::socket_open. */ nsapi_error_t open(NetworkStack *stack); @@ -61,28 +65,34 @@ public: /** Close any open connection, and deallocate any memory associated * with the socket. Called from destructor if socket is not closed. * - * @return 0 on success, negative error code on failure (@see nsapi_types.h). + * @retval NSAPI_ERROR_OK on success. + * @retval NSAPI_ERROR_NO_SOCKET if socket is not open. + * @retval int negative error codes for stack-related failures. + * See @ref NetworkStack::socket_close. */ virtual nsapi_error_t close(); /** Subscribe to an IP multicast group. * * @param address Multicast group IP address. - * @return 0 on success, negative error code on failure (@see nsapi_types.h). + * @return NSAPI_ERROR_OK on success, negative error code on failure (@see InternetSocket::setsockopt). */ int join_multicast_group(const SocketAddress &address); /** Leave an IP multicast group. * * @param address Multicast group IP address. - * @return 0 on success, negative error code on failure (@see nsapi_types.h). + * @return NSAPI_ERROR_OK on success, negative error code on failure (@see InternetSocket::setsockopt). */ int leave_multicast_group(const SocketAddress &address); /** Bind the socket to a port on which to receive data. * * @param port Local port to bind. - * @return 0 on success, negative error code on failure (@see nsapi_types.h). + * @retval NSAPI_ERROR_OK on success. + * @retval NSAPI_ERROR_NO_SOCKET if socket is not open. + * @retval int negative error codes for stack-related failures. + * See @ref NetworkStack::socket_bind. */ nsapi_error_t bind(uint16_t port); @@ -91,7 +101,10 @@ public: * * @param address Null-terminated local address to bind. * @param port Local port to bind. - * @return 0 on success, negative error code on failure (@see nsapi_types.h). + * @retval NSAPI_ERROR_OK on success. + * @retval NSAPI_ERROR_NO_SOCKET if socket is not open. + * @retval int negative error codes for stack-related failures. + * See @ref NetworkStack::socket_bind. */ nsapi_error_t bind(const char *address, uint16_t port); diff --git a/features/netsocket/Socket.h b/features/netsocket/Socket.h index 48e3bca532..2384554bc3 100644 --- a/features/netsocket/Socket.h +++ b/features/netsocket/Socket.h @@ -49,7 +49,8 @@ public: * Closes any open connection and deallocates any memory associated * with the socket. Called from destructor if socket is not closed. * - * @return NSAPI_ERROR_OK on success, negative error code on failure + * @return NSAPI_ERROR_OK on success. + * Negative subclass-dependent error code on failure. */ virtual nsapi_error_t close() = 0; @@ -68,7 +69,8 @@ public: * a new one before attempting to reconnect. * * @param address The SocketAddress of the remote peer. - * @return NSAPI_ERROR_OK on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success. + * Negative subclass-dependent error code on failure. */ virtual nsapi_error_t connect(const SocketAddress &address) = 0; @@ -84,8 +86,8 @@ public: * * @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. + * @return NSAPI_ERROR_OK on success. + * Negative subclass-dependent error code on failure. */ virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size) = 0; @@ -105,8 +107,8 @@ public: * * @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 + * @return Number of received bytes on success, negative, subclass-dependent + * error code on failure. If no data is available to be received * and the peer has performed an orderly shutdown, * recv() returns 0. */ @@ -125,7 +127,7 @@ public: * @param address Remote address * @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 + * @return Number of sent bytes on success, negative subclass-dependent error * code on failure */ virtual nsapi_size_or_error_t sendto(const SocketAddress &address, @@ -148,8 +150,8 @@ public: * @param address Destination for the source address or NULL * @param data Destination buffer for datagram received from the host * @param size Size of the buffer in bytes - * @return Number of received bytes on success, negative error - * code on failure + * @return Number of received bytes on success, negative subclass-dependent + * error code on failure */ virtual nsapi_size_or_error_t recvfrom(SocketAddress *address, void *data, nsapi_size_t size) = 0; @@ -160,7 +162,8 @@ public: * data. If the IP address is zeroed, only the port is bound. * * @param address Local address to bind. - * @return NSAPI_ERROR_OK on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success, negative subclass-dependent error + * code on failure. */ virtual nsapi_error_t bind(const SocketAddress &address) = 0; @@ -222,7 +225,9 @@ public: * @param optname Level-specific option name. * @param optval Option value. * @param optlen Length of the option value. - * @return NSAPI_ERROR_OK on success, negative error code on failure. + * @retval NSAPI_ERROR_OK on success. + * @retval NSAPI_ERROR_NO_SOCKET if socket is not open. + * @retval int Negative error code on failure, see @ref NetworkStack::setsockopt. */ virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0; @@ -239,7 +244,9 @@ public: * @param optname Level-specific option name. * @param optval Destination for option value. * @param optlen Length of the option value. - * @return NSAPI_ERROR_OK on success, negative error code on failure. + * @retval NSAPI_ERROR_OK on success. + * @retval NSAPI_ERROR_NO_SOCKET if socket is not open. + * @retval int Negative error code on failure, see @ref NetworkStack::getsockopt. */ virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) = 0; @@ -276,7 +283,9 @@ public: * associated. * * @param address Pointer to SocketAddress structure. - * @return NSAPI_ERROR_OK on success, negative error code on failure. + * @retval NSAPI_ERROR_OK on success. + * @retval NSAPI_ERROR_NO_SOCKET if socket is not connected. + * @retval NSAPI_ERROR_NO_CONNECTION if the remote peer was not set. */ virtual nsapi_error_t getpeername(SocketAddress *address) = 0; }; diff --git a/features/netsocket/TCPSocket.h b/features/netsocket/TCPSocket.h index 4acddce8ce..958dc68dca 100644 --- a/features/netsocket/TCPSocket.h +++ b/features/netsocket/TCPSocket.h @@ -77,7 +77,13 @@ public: * * @param host Hostname of the remote host * @param port Port of the remote host - * @return 0 on success, negative error code on failure + * @retval NSAPI_ERROR_OK on success + * @retval NSAPI_ERROR_IN_PROGRESS if the operation is ongoing + * @retval NSAPI_ERROR_NO_SOCKET if the socket has not been allocated + * @retval NSAPI_ERROR_DNS_FAILURE if the DNS address of host could not be resolved + * @retval NSAPI_ERROR_IS_CONNECTED if the connection is already established + * @retval int Other negative error codes for stack-related failures. + * See NetworkStack::socket_connect(). */ nsapi_error_t connect(const char *host, uint16_t port); @@ -87,7 +93,13 @@ public: * indicated address. * * @param address The SocketAddress of the remote host - * @return 0 on success, negative error code on failure + * @retval NSAPI_ERROR_OK on success + * @retval NSAPI_ERROR_IN_PROGRESS if the operation is ongoing + * @retval NSAPI_ERROR_NO_SOCKET if the socket has not been allocated + * @retval NSAPI_ERROR_DNS_FAILURE if the DNS address of host could not be resolved + * @retval NSAPI_ERROR_IS_CONNECTED if the connection is already established + * @retval int Other negative error codes for stack-related failures. + * See NetworkStack::socket_connect(). */ virtual nsapi_error_t connect(const SocketAddress &address); @@ -102,8 +114,12 @@ public: * * @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 int Other negative error codes for stack-related failures. + * See @ref NetworkStack::socket_send. */ virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size); @@ -118,10 +134,12 @@ public: * * @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 received 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 int Other negative error codes for stack-related failures. + * See @ref NetworkStack::socket_recv. */ virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size); @@ -136,8 +154,12 @@ public: * @param address Remote address * @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 int Other negative error codes for stack-related failures. + * See @ref NetworkStack::socket_send. */ virtual nsapi_size_or_error_t sendto(const SocketAddress &address, const void *data, nsapi_size_t size); @@ -154,8 +176,12 @@ public: * @param address Destination for the source address or NULL * @param data Destination buffer for datagram received from the host * @param size Size of the buffer in bytes - * @return Number of received bytes on success, negative error - * code on failure + * @retval int Number of received 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 int Other negative error codes for stack-related failures. + * See @ref NetworkStack::socket_recv. */ virtual nsapi_size_or_error_t recvfrom(SocketAddress *address, void *data, nsapi_size_t size); @@ -182,7 +208,10 @@ public: * * @param backlog Number of pending connections that can be queued * simultaneously, defaults to 1 - * @return 0 on success, negative error code on failure + * @retval NSAPI_ERROR_OK on success + * @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly + * @retval int Other negative error codes for stack-related failures. + * See @ref NetworkStack::socket_listen. */ virtual nsapi_error_t listen(int backlog = 1); diff --git a/features/netsocket/TLSSocket.h b/features/netsocket/TLSSocket.h index 98b4347f70..c4128062fa 100644 --- a/features/netsocket/TLSSocket.h +++ b/features/netsocket/TLSSocket.h @@ -65,7 +65,7 @@ public: * clear internal TLS memory structures. * * @param stack Network stack as target for socket. - * @return NSAPI_ERROR_OK on success, negative error code on failure. + * @return NSAPI_ERROR_OK on success. See @ref TCPSocket::open */ virtual nsapi_error_t open(NetworkStack *stack) { @@ -91,6 +91,7 @@ public: * @param host Hostname of the remote host. * @param port Port of the remote host. * @return NSAPI_ERROR_OK on success, negative error code on failure. + * See @ref TLSSocketWrapper::connect. */ nsapi_error_t connect(const char *host, uint16_t port); diff --git a/features/netsocket/TLSSocketWrapper.h b/features/netsocket/TLSSocketWrapper.h index 7bd423c539..2a3e03e567 100644 --- a/features/netsocket/TLSSocketWrapper.h +++ b/features/netsocket/TLSSocketWrapper.h @@ -81,7 +81,9 @@ public: * * @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); @@ -99,7 +101,8 @@ public: * @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 +111,8 @@ public: * * @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 +123,12 @@ public: * * @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 +139,26 @@ public: * * @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 +234,11 @@ protected: * 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);