Skip to content

Commit 40df54a

Browse files
michalpasztamobicamichalpasztamobica
committed
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.
1 parent df79609 commit 40df54a

File tree

7 files changed

+153
-56
lines changed

7 files changed

+153
-56
lines changed

‎features/netsocket/DTLSSocket.h

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,8 @@ class DTLSSocket : public DTLSSocketWrapper {
7171
* socket's constructor.
7272
*
7373
* @param stack Network stack as target for socket.
74-
* @return 0 on success, negative error code on failure.
74+
* @return NSAPI_ERROR_OK on success, negative error code on failure.
75+
* See @ref UDPSocket::open.
7576
*/
7677
virtual nsapi_error_t open(NetworkStack *stack)
7778
{
@@ -93,7 +94,8 @@ class DTLSSocket : public DTLSSocketWrapper {
9394
*
9495
* @param host Hostname of the remote host.
9596
* @param port Port of the remote host.
96-
* @return 0 on success, negative error code on failure.
97+
* @return NSAPI_ERROR_OK on success, negative error code on failure.
98+
* See @ref TLSSocketWrapper::connect.
9799
*/
98100
nsapi_error_t connect(const char *host, uint16_t port);
99101

‎features/netsocket/InternetSocket.h

Lines changed: 19 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,11 @@ class InternetSocket : public Socket {
4646
* @note Not needed if stack is passed to the socket's constructor.
4747
*
4848
* @param stack Network stack as target for socket.
49-
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
49+
* @retval NSAPI_ERROR_OK on success.
50+
* @retval NSAPI_ERROR_PARAMETER in case the provided stack was invalid
51+
* or a stack was already created and socket opened successfully.
52+
* @retval int negative error codes for stack-related failures.
53+
* See @ref NetworkStack::socket_open.
5054
*/
5155
nsapi_error_t open(NetworkStack *stack);
5256

@@ -61,28 +65,34 @@ class InternetSocket : public Socket {
6165
/** Close any open connection, and deallocate any memory associated
6266
* with the socket. Called from destructor if socket is not closed.
6367
*
64-
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
68+
* @retval NSAPI_ERROR_OK on success.
69+
* @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
70+
* @retval int negative error codes for stack-related failures.
71+
* See @ref NetworkStack::socket_close.
6572
*/
6673
virtual nsapi_error_t close();
6774

6875
/** Subscribe to an IP multicast group.
6976
*
7077
* @param address Multicast group IP address.
71-
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
78+
* @return NSAPI_ERROR_OK on success, negative error code on failure (@see InternetSocket::setsockopt).
7279
*/
7380
int join_multicast_group(const SocketAddress &address);
7481

7582
/** Leave an IP multicast group.
7683
*
7784
* @param address Multicast group IP address.
78-
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
85+
* @return NSAPI_ERROR_OK on success, negative error code on failure (@see InternetSocket::setsockopt).
7986
*/
8087
int leave_multicast_group(const SocketAddress &address);
8188

8289
/** Bind the socket to a port on which to receive data.
8390
*
8491
* @param port Local port to bind.
85-
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
92+
* @retval NSAPI_ERROR_OK on success.
93+
* @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
94+
* @retval int negative error codes for stack-related failures.
95+
* See @ref NetworkStack::socket_bind.
8696
*/
8797
nsapi_error_t bind(uint16_t port);
8898

@@ -91,7 +101,10 @@ class InternetSocket : public Socket {
91101
*
92102
* @param address Null-terminated local address to bind.
93103
* @param port Local port to bind.
94-
* @return 0 on success, negative error code on failure (@see nsapi_types.h).
104+
* @retval NSAPI_ERROR_OK on success.
105+
* @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
106+
* @retval int negative error codes for stack-related failures.
107+
* See @ref NetworkStack::socket_bind.
95108
*/
96109
nsapi_error_t bind(const char *address, uint16_t port);
97110

‎features/netsocket/Socket.h

Lines changed: 22 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,8 @@ class Socket {
4949
* Closes any open connection and deallocates any memory associated
5050
* with the socket. Called from destructor if socket is not closed.
5151
*
52-
* @return NSAPI_ERROR_OK on success, negative error code on failure
52+
* @return NSAPI_ERROR_OK on success.
53+
* Negative subclass-dependent error code on failure.
5354
*/
5455
virtual nsapi_error_t close() = 0;
5556

@@ -68,7 +69,8 @@ class Socket {
6869
* a new one before attempting to reconnect.
6970
*
7071
* @param address The SocketAddress of the remote peer.
71-
* @return NSAPI_ERROR_OK on success, negative error code on failure.
72+
* @return NSAPI_ERROR_OK on success.
73+
* Negative subclass-dependent error code on failure.
7274
*/
7375
virtual nsapi_error_t connect(const SocketAddress &address) = 0;
7476

@@ -84,8 +86,8 @@ class Socket {
8486
*
8587
* @param data Buffer of data to send to the host.
8688
* @param size Size of the buffer in bytes.
87-
* @return Number of sent bytes on success, negative error
88-
* code on failure.
89+
* @return NSAPI_ERROR_OK on success.
90+
* Negative subclass-dependent error code on failure.
8991
*/
9092
virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size) = 0;
9193

@@ -105,8 +107,8 @@ class Socket {
105107
*
106108
* @param data Destination buffer for data received from the host.
107109
* @param size Size of the buffer in bytes.
108-
* @return Number of received bytes on success, negative error
109-
* code on failure. If no data is available to be received
110+
* @return Number of received bytes on success, negative, subclass-dependent
111+
* error code on failure. If no data is available to be received
110112
* and the peer has performed an orderly shutdown,
111113
* recv() returns 0.
112114
*/
@@ -125,7 +127,7 @@ class Socket {
125127
* @param address Remote address
126128
* @param data Buffer of data to send to the host
127129
* @param size Size of the buffer in bytes
128-
* @return Number of sent bytes on success, negative error
130+
* @return Number of sent bytes on success, negative subclass-dependent error
129131
* code on failure
130132
*/
131133
virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
@@ -148,8 +150,8 @@ class Socket {
148150
* @param address Destination for the source address or NULL
149151
* @param data Destination buffer for datagram received from the host
150152
* @param size Size of the buffer in bytes
151-
* @return Number of received bytes on success, negative error
152-
* code on failure
153+
* @return Number of received bytes on success, negative subclass-dependent
154+
* error code on failure
153155
*/
154156
virtual nsapi_size_or_error_t recvfrom(SocketAddress *address,
155157
void *data, nsapi_size_t size) = 0;
@@ -160,7 +162,8 @@ class Socket {
160162
* data. If the IP address is zeroed, only the port is bound.
161163
*
162164
* @param address Local address to bind.
163-
* @return NSAPI_ERROR_OK on success, negative error code on failure.
165+
* @return NSAPI_ERROR_OK on success, negative subclass-dependent error
166+
* code on failure.
164167
*/
165168
virtual nsapi_error_t bind(const SocketAddress &address) = 0;
166169

@@ -222,7 +225,9 @@ class Socket {
222225
* @param optname Level-specific option name.
223226
* @param optval Option value.
224227
* @param optlen Length of the option value.
225-
* @return NSAPI_ERROR_OK on success, negative error code on failure.
228+
* @retval NSAPI_ERROR_OK on success.
229+
* @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
230+
* @retval int Negative error code on failure, see @ref NetworkStack::setsockopt.
226231
*/
227232
virtual nsapi_error_t setsockopt(int level, int optname, const void *optval, unsigned optlen) = 0;
228233

@@ -239,7 +244,9 @@ class Socket {
239244
* @param optname Level-specific option name.
240245
* @param optval Destination for option value.
241246
* @param optlen Length of the option value.
242-
* @return NSAPI_ERROR_OK on success, negative error code on failure.
247+
* @retval NSAPI_ERROR_OK on success.
248+
* @retval NSAPI_ERROR_NO_SOCKET if socket is not open.
249+
* @retval int Negative error code on failure, see @ref NetworkStack::getsockopt.
243250
*/
244251
virtual nsapi_error_t getsockopt(int level, int optname, void *optval, unsigned *optlen) = 0;
245252

@@ -276,7 +283,9 @@ class Socket {
276283
* associated.
277284
*
278285
* @param address Pointer to SocketAddress structure.
279-
* @return NSAPI_ERROR_OK on success, negative error code on failure.
286+
* @retval NSAPI_ERROR_OK on success.
287+
* @retval NSAPI_ERROR_NO_SOCKET if socket is not connected.
288+
* @retval NSAPI_ERROR_NO_CONNECTION if the remote peer was not set.
280289
*/
281290
virtual nsapi_error_t getpeername(SocketAddress *address) = 0;
282291
};

‎features/netsocket/TCPSocket.h

Lines changed: 42 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -77,7 +77,13 @@ class TCPSocket : public InternetSocket {
7777
*
7878
* @param host Hostname of the remote host
7979
* @param port Port of the remote host
80-
* @return 0 on success, negative error code on failure
80+
* @retval NSAPI_ERROR_OK on success
81+
* @retval NSAPI_ERROR_IN_PROGRESS if the operation is ongoing
82+
* @retval NSAPI_ERROR_NO_SOCKET if the socket has not been allocated
83+
* @retval NSAPI_ERROR_DNS_FAILURE if the DNS address of host could not be resolved
84+
* @retval NSAPI_ERROR_IS_CONNECTED if the connection is already established
85+
* @retval int Other negative error codes for stack-related failures.
86+
* See NetworkStack::socket_connect().
8187
*/
8288
nsapi_error_t connect(const char *host, uint16_t port);
8389

@@ -87,7 +93,13 @@ class TCPSocket : public InternetSocket {
8793
* indicated address.
8894
*
8995
* @param address The SocketAddress of the remote host
90-
* @return 0 on success, negative error code on failure
96+
* @retval NSAPI_ERROR_OK on success
97+
* @retval NSAPI_ERROR_IN_PROGRESS if the operation is ongoing
98+
* @retval NSAPI_ERROR_NO_SOCKET if the socket has not been allocated
99+
* @retval NSAPI_ERROR_DNS_FAILURE if the DNS address of host could not be resolved
100+
* @retval NSAPI_ERROR_IS_CONNECTED if the connection is already established
101+
* @retval int Other negative error codes for stack-related failures.
102+
* See NetworkStack::socket_connect().
91103
*/
92104
virtual nsapi_error_t connect(const SocketAddress &address);
93105

@@ -102,8 +114,12 @@ class TCPSocket : public InternetSocket {
102114
*
103115
* @param data Buffer of data to send to the host
104116
* @param size Size of the buffer in bytes
105-
* @return Number of sent bytes on success, negative error
106-
* code on failure
117+
* @retval int Number of sent bytes on success
118+
* @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
119+
* @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
120+
* and send cannot be performed immediately
121+
* @retval int Other negative error codes for stack-related failures.
122+
* See @ref NetworkStack::socket_send.
107123
*/
108124
virtual nsapi_size_or_error_t send(const void *data, nsapi_size_t size);
109125

@@ -118,10 +134,12 @@ class TCPSocket : public InternetSocket {
118134
*
119135
* @param data Destination buffer for data received from the host
120136
* @param size Size of the buffer in bytes
121-
* @return Number of received bytes on success, negative error
122-
* code on failure. If no data is available to be received
123-
* and the peer has performed an orderly shutdown,
124-
* recv() returns 0.
137+
* @retval int Number of received bytes on success
138+
* @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
139+
* @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
140+
* and send cannot be performed immediately
141+
* @retval int Other negative error codes for stack-related failures.
142+
* See @ref NetworkStack::socket_recv.
125143
*/
126144
virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size);
127145

@@ -136,8 +154,12 @@ class TCPSocket : public InternetSocket {
136154
* @param address Remote address
137155
* @param data Buffer of data to send to the host
138156
* @param size Size of the buffer in bytes
139-
* @return Number of sent bytes on success, negative error
140-
* code on failure
157+
* @retval int Number of sent bytes on success
158+
* @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
159+
* @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
160+
* and send cannot be performed immediately
161+
* @retval int Other negative error codes for stack-related failures.
162+
* See @ref NetworkStack::socket_send.
141163
*/
142164
virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
143165
const void *data, nsapi_size_t size);
@@ -154,8 +176,12 @@ class TCPSocket : public InternetSocket {
154176
* @param address Destination for the source address or NULL
155177
* @param data Destination buffer for datagram received from the host
156178
* @param size Size of the buffer in bytes
157-
* @return Number of received bytes on success, negative error
158-
* code on failure
179+
* @retval int Number of received bytes on success
180+
* @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
181+
* @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
182+
* and send cannot be performed immediately
183+
* @retval int Other negative error codes for stack-related failures.
184+
* See @ref NetworkStack::socket_recv.
159185
*/
160186
virtual nsapi_size_or_error_t recvfrom(SocketAddress *address,
161187
void *data, nsapi_size_t size);
@@ -182,7 +208,10 @@ class TCPSocket : public InternetSocket {
182208
*
183209
* @param backlog Number of pending connections that can be queued
184210
* simultaneously, defaults to 1
185-
* @return 0 on success, negative error code on failure
211+
* @retval NSAPI_ERROR_OK on success
212+
* @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly
213+
* @retval int Other negative error codes for stack-related failures.
214+
* See @ref NetworkStack::socket_listen.
186215
*/
187216
virtual nsapi_error_t listen(int backlog = 1);
188217

‎features/netsocket/TLSSocket.h

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ class TLSSocket : public TLSSocketWrapper {
6565
* clear internal TLS memory structures.
6666
*
6767
* @param stack Network stack as target for socket.
68-
* @return NSAPI_ERROR_OK on success, negative error code on failure.
68+
* @return NSAPI_ERROR_OK on success. See @ref TCPSocket::open
6969
*/
7070
virtual nsapi_error_t open(NetworkStack *stack)
7171
{
@@ -91,6 +91,7 @@ class TLSSocket : public TLSSocketWrapper {
9191
* @param host Hostname of the remote host.
9292
* @param port Port of the remote host.
9393
* @return NSAPI_ERROR_OK on success, negative error code on failure.
94+
* See @ref TLSSocketWrapper::connect.
9495
*/
9596
nsapi_error_t connect(const char *host, uint16_t port);
9697

0 commit comments

Comments
 (0)