ARMmbed
/
mbed-os
mirror of https://github.com/ARMmbed/mbed-os.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Document Socket API functions return values. 

Describe the return values with as much detail as possible, to let user only check the relevant return codes, instead of all nsapi_error_t. Refer to underlying APIs wherever possible.
pull/11808/head
Michal Paszta 2019-10-31 09:32:34 +02:00
parent c93c181b6a
commit 87211e9158
7 changed files with 152 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
features/netsocket/DTLSSocket.h
View File

@ -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);

43
features/netsocket/InternetDatagramSocket.h
View File

@ -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);

25
features/netsocket/InternetSocket.h
View File

@ -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);

35
features/netsocket/Socket.h
View File

@ -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;
};

55
features/netsocket/TCPSocket.h
View File

@ -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);

3
features/netsocket/TLSSocket.h
View File

@ -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);

41
features/netsocket/TLSSocketWrapper.h
View File

@ -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);