Skip to content

Commit 0d0120a

Browse files
0xc01700xc0170
authored
Merge pull request #11808 from michalpasztamobica/api_hardening
Document Socket API functions return values.
2 parents 355336c + 87211e9 commit 0d0120a

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)