Skip to content

Commit 87211e9

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 c93c181 commit 87211e9

File tree

7 files changed

+152
-56
lines changed

7 files changed

+152
-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/InternetDatagramSocket.h

Lines changed: 32 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,12 @@ class InternetDatagramSocket : public InternetSocket {
4040
* @param port Port of the remote host.
4141
* @param data Buffer of data to send to the host.
4242
* @param size Size of the buffer in bytes.
43-
* @return Number of sent bytes on success, negative error
44-
* code on failure.
43+
* @retval int Number of sent bytes on success.
44+
* @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
45+
* @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
46+
* and send cannot be performed immediately.
47+
* @retval int Other negative error codes for stack-related failures.
48+
* See @ref NetworkStack::socket_send.
4549
*/
4650
virtual nsapi_size_or_error_t sendto(const char *host, uint16_t port,
4751
const void *data, nsapi_size_t size);
@@ -55,8 +59,13 @@ class InternetDatagramSocket : public InternetSocket {
5559
* @param address The SocketAddress of the remote host.
5660
* @param data Buffer of data to send to the host.
5761
* @param size Size of the buffer in bytes.
58-
* @return Number of sent bytes on success, negative error
59-
* code on failure.
62+
* @retval NSAPI_ERROR_DNS_FAILURE in case the address parameter cannot
63+
* be resolved.
64+
* @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
65+
* @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
66+
* and send cannot be performed immediately.
67+
* @retval int Other negative error codes for stack-related failures.
68+
* See \ref NetworkStack::socket_send.
6069
*/
6170
virtual nsapi_size_or_error_t sendto(const SocketAddress &address,
6271
const void *data, nsapi_size_t size);
@@ -77,8 +86,12 @@ class InternetDatagramSocket : public InternetSocket {
7786
* @param address Destination for the source address or NULL.
7887
* @param data Destination buffer for RAW data to be received from the host.
7988
* @param size Size of the buffer in bytes.
80-
* @return Number of received bytes on success, negative error
81-
* code on failure.
89+
* @retval int Number of received bytes on success.
90+
* @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
91+
* @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
92+
* and send cannot be performed immediately.
93+
* @retval int Other negative error codes for stack-related failures.
94+
* See \ref NetworkStack::socket_recv.
8295
*/
8396
virtual nsapi_size_or_error_t recvfrom(SocketAddress *address,
8497
void *data, nsapi_size_t size);
@@ -88,7 +101,7 @@ class InternetDatagramSocket : public InternetSocket {
88101
* SocketAddress must be in the address parameter.
89102
*
90103
* @param address The SocketAddress of the remote host.
91-
* @return 0 on success, negative error code on failure.
104+
* @return NSAPI_ERROR_OK on success.
92105
*/
93106
virtual nsapi_error_t connect(const SocketAddress &address);
94107

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

@@ -119,8 +136,12 @@ class InternetDatagramSocket : public InternetSocket {
119136
*
120137
* @param data Pointer to buffer for data received from the host.
121138
* @param size Size of the buffer in bytes.
122-
* @return Number of received bytes on success, negative error
123-
* code on failure.
139+
* @retval int Number of received bytes on success.
140+
* @retval NSAPI_ERROR_NO_SOCKET in case socket was not created correctly.
141+
* @retval NSAPI_ERROR_WOULD_BLOCK in case non-blocking mode is enabled
142+
* and send cannot be performed immediately.
143+
* @retval int Other negative error codes for stack-related failures.
144+
* See \ref NetworkStack::socket_recv.
124145
*/
125146
virtual nsapi_size_or_error_t recv(void *data, nsapi_size_t size);
126147

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

0 commit comments

Comments
 (0)