Skip to content

Commit e3f0699

Browse files
paul-szczepanek-armCruz Monrreal II
paul-szczepanek-arm
authored and
Cruz Monrreal II
committed
return codes
1 parent 2fda1c2 commit e3f0699

File tree

3 files changed

+46
-46
lines changed

3 files changed

+46
-46
lines changed

‎features/netsocket/DNS.h

Lines changed: 19 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -20,24 +20,24 @@
2020
class DNS {
2121
public:
2222

23-
/** Translates a hostname to an IP address with specific version
23+
/** Translate a hostname to an IP address with specific version.
2424
*
2525
* The hostname may be either a domain name or an IP address. If the
2626
* hostname is an IP address, no network transactions will be performed.
2727
*
2828
* If no stack-specific DNS resolution is provided, the hostname
2929
* will be resolve using a UDP socket on the stack.
3030
*
31-
* @param host Hostname to resolve
32-
* @param address Destination for the host SocketAddress
31+
* @param host Hostname to resolve.
32+
* @param address Pointer to a SocketAddress to store the result.
3333
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates
34-
* version is chosen by the stack (defaults to NSAPI_UNSPEC)
35-
* @return 0 on success, negative error code on failure
34+
* version is chosen by the stack (defaults to NSAPI_UNSPEC).
35+
* @return NSAPI_ERROR_OK on success, negative error code on failure.
3636
*/
3737
virtual nsapi_error_t gethostbyname(const char *host,
3838
SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC) = 0;
3939

40-
/** Hostname translation callback (asynchronous)
40+
/** Hostname translation callback for gethostbyname_async.
4141
*
4242
* Callback will be called after DNS resolution completes or a failure occurs.
4343
*
@@ -47,12 +47,12 @@ class DNS {
4747
* The callback should not perform expensive operations such as socket recv/send
4848
* calls or blocking operations.
4949
*
50-
* @param status 0 on success, negative error code on failure
51-
* @param address On success, destination for the host SocketAddress
50+
* @param result NSAPI_ERROR_OK on success, negative error code on failure.
51+
* @param address On success, destination for the host SocketAddress.
5252
*/
5353
typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t;
5454

55-
/** Translates a hostname to an IP address (asynchronous)
55+
/** Translate a hostname to an IP address (asynchronous)
5656
*
5757
* The hostname may be either a domain name or an IP address. If the
5858
* hostname is an IP address, no network transactions will be performed.
@@ -65,31 +65,31 @@ class DNS {
6565
* is success (IP address was found from DNS cache), callback will be called
6666
* before function returns.
6767
*
68-
* @param host Hostname to resolve
69-
* @param callback Callback that is called for result
68+
* @param host Hostname to resolve.
69+
* @param callback Callback that is called to return the result.
7070
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates
71-
* version is chosen by the stack (defaults to NSAPI_UNSPEC)
72-
* @return 0 on immediate success,
71+
* version is chosen by the stack (defaults to NSAPI_UNSPEC).
72+
* @return NSAPI_ERROR_OK on immediate success,
7373
* negative error code on immediate failure or
7474
* a positive unique id that represents the hostname translation operation
75-
* and can be passed to cancel
75+
* and can be passed to cancel.
7676
*/
7777
virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback,
7878
nsapi_version_t version = NSAPI_UNSPEC) = 0;
7979

80-
/** Cancels asynchronous hostname translation
80+
/** Cancel asynchronous hostname translation.
8181
*
8282
* When translation is cancelled, callback will not be called.
8383
*
84-
* @param id Unique id of the hostname translation operation
85-
* @return 0 on success, negative error code on failure
84+
* @param id Unique id of the hostname translation operation returned by gethostbyname_async.
85+
* @return NSAPI_ERROR_OK on success, negative error code on failure.
8686
*/
8787
virtual nsapi_error_t gethostbyname_async_cancel(int id) = 0;
8888

8989
/** Add a domain name server to list of servers to query
9090
*
91-
* @param address Destination for the host address
92-
* @return 0 on success, negative error code on failure
91+
* @param address DNS server host address.
92+
* @return NSAPI_ERROR_OK on success, negative error code on failure.
9393
*/
9494
virtual nsapi_error_t add_dns_server(const SocketAddress &address) = 0;
9595
};

‎features/netsocket/NetworkInterface.h

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -118,7 +118,7 @@ class NetworkInterface: public DNS {
118118
* @param ip_address Null-terminated representation of the local IP address
119119
* @param netmask Null-terminated representation of the local network mask
120120
* @param gateway Null-terminated representation of the local gateway
121-
* @return 0 on success, negative error code on failure
121+
* @return NSAPI_ERROR_OK on success, negative error code on failure
122122
*/
123123
virtual nsapi_error_t set_network(const char *ip_address, const char *netmask, const char *gateway);
124124

@@ -128,19 +128,19 @@ class NetworkInterface: public DNS {
128128
* that the network is disconnected.
129129
*
130130
* @param dhcp True to enable DHCP.
131-
* @return 0 on success, negative error code on failure.
131+
* @return NSAPI_ERROR_OK on success, negative error code on failure.
132132
*/
133133
virtual nsapi_error_t set_dhcp(bool dhcp);
134134

135135
/** Start the interface.
136136
*
137-
* @return 0 on success, negative error code on failure.
137+
* @return NSAPI_ERROR_OK on success, negative error code on failure.
138138
*/
139139
virtual nsapi_error_t connect() = 0;
140140

141141
/** Stop the interface.
142142
*
143-
* @return 0 on success, negative error code on failure.
143+
* @return NSAPI_ERROR_OK on success, negative error code on failure.
144144
*/
145145
virtual nsapi_error_t disconnect() = 0;
146146

@@ -153,10 +153,10 @@ class NetworkInterface: public DNS {
153153
* will be resolve using a UDP socket on the stack.
154154
*
155155
* @param host Hostname to resolve.
156-
* @param address Destination for the host SocketAddress.
156+
* @param address Pointer to a SocketAddress to store the result.
157157
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates
158158
* version is chosen by the stack (defaults to NSAPI_UNSPEC).
159-
* @return 0 on success, negative error code on failure.
159+
* @return NSAPI_ERROR_OK on success, negative error code on failure.
160160
*/
161161
virtual nsapi_error_t gethostbyname(const char *host,
162162
SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC);
@@ -171,7 +171,7 @@ class NetworkInterface: public DNS {
171171
* The callback should not perform expensive operations such as socket recv/send
172172
* calls or blocking operations.
173173
*
174-
* @param result 0 on success, negative error code on failure.
174+
* @param result NSAPI_ERROR_OK on success, negative error code on failure.
175175
* @param address On success, destination for the host SocketAddress.
176176
*/
177177
typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t;
@@ -207,14 +207,14 @@ class NetworkInterface: public DNS {
207207
*
208208
* @param id Unique id of the hostname translation operation (returned
209209
* by gethostbyname_async)
210-
* @return 0 on success, negative error code on failure.
210+
* @return NSAPI_ERROR_OK on success, negative error code on failure.
211211
*/
212212
virtual nsapi_error_t gethostbyname_async_cancel(int id);
213213

214214
/** Add a domain name server to list of servers to query
215215
*
216216
* @param address Address for the dns host.
217-
* @return 0 on success, negative error code on failure.
217+
* @return NSAPI_ERROR_OK on success, negative error code on failure.
218218
*/
219219
virtual nsapi_error_t add_dns_server(const SocketAddress &address);
220220

@@ -237,7 +237,7 @@ class NetworkInterface: public DNS {
237237
/** Set blocking status of connect() which by default should be blocking.
238238
*
239239
* @param blocking Use true to make connect() blocking.
240-
* @return 0 on success, negative error code on failure.
240+
* @return NSAPI_ERROR_OK on success, negative error code on failure.
241241
*/
242242
virtual nsapi_error_t set_blocking(bool blocking);
243243

‎features/netsocket/NetworkStack.h

Lines changed: 17 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -54,10 +54,10 @@ class NetworkStack: public DNS {
5454
* will be resolve using a UDP socket on the stack.
5555
*
5656
* @param host Hostname to resolve
57-
* @param address Destination for the host SocketAddress
57+
* @param address Pointer to a SocketAddress to store the result.
5858
* @param version IP version of address to resolve, NSAPI_UNSPEC indicates
5959
* version is chosen by the stack (defaults to NSAPI_UNSPEC)
60-
* @return 0 on success, negative error code on failure
60+
* @return NSAPI_ERROR_OK on success, negative error code on failure
6161
*/
6262
virtual nsapi_error_t gethostbyname(const char *host,
6363
SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC);
@@ -72,7 +72,7 @@ class NetworkStack: public DNS {
7272
* The callback should not perform expensive operations such as socket recv/send
7373
* calls or blocking operations.
7474
*
75-
* @param status 0 on success, negative error code on failure
75+
* @param status NSAPI_ERROR_OK on success, negative error code on failure
7676
* @param address On success, destination for the host SocketAddress
7777
*/
7878
typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t;
@@ -107,14 +107,14 @@ class NetworkStack: public DNS {
107107
* When translation is cancelled, callback will not be called.
108108
*
109109
* @param id Unique id of the hostname translation operation
110-
* @return 0 on success, negative error code on failure
110+
* @return NSAPI_ERROR_OK on success, negative error code on failure
111111
*/
112112
virtual nsapi_error_t gethostbyname_async_cancel(int id);
113113

114114
/** Add a domain name server to list of servers to query
115115
*
116116
* @param address Destination for the host address
117-
* @return 0 on success, negative error code on failure
117+
* @return NSAPI_ERROR_OK on success, negative error code on failure
118118
*/
119119
virtual nsapi_error_t add_dns_server(const SocketAddress &address);
120120

@@ -125,7 +125,7 @@ class NetworkStack: public DNS {
125125
*
126126
* @param index Index of the DNS server, starts from zero
127127
* @param address Destination for the host address
128-
* @return 0 on success, negative error code on failure
128+
* @return NSAPI_ERROR_OK on success, negative error code on failure
129129
*/
130130
virtual nsapi_error_t get_dns_server(int index, SocketAddress *address);
131131

@@ -142,7 +142,7 @@ class NetworkStack: public DNS {
142142
* @param optname Level-specific option name
143143
* @param optval Option value
144144
* @param optlen Length of the option value
145-
* @return 0 on success, negative error code on failure
145+
* @return NSAPI_ERROR_OK on success, negative error code on failure
146146
*/
147147
virtual nsapi_error_t setstackopt(int level, int optname, const void *optval, unsigned optlen);
148148

@@ -156,7 +156,7 @@ class NetworkStack: public DNS {
156156
* @param optname Level-specific option name
157157
* @param optval Destination for option value
158158
* @param optlen Length of the option value
159-
* @return 0 on success, negative error code on failure
159+
* @return NSAPI_ERROR_OK on success, negative error code on failure
160160
*/
161161
virtual nsapi_error_t getstackopt(int level, int optname, void *optval, unsigned *optlen);
162162

@@ -182,7 +182,7 @@ class NetworkStack: public DNS {
182182
*
183183
* @param handle Destination for the handle to a newly created socket
184184
* @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
185-
* @return 0 on success, negative error code on failure
185+
* @return NSAPI_ERROR_OK on success, negative error code on failure
186186
*/
187187
virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto) = 0;
188188

@@ -192,7 +192,7 @@ class NetworkStack: public DNS {
192192
* with the socket.
193193
*
194194
* @param handle Socket handle
195-
* @return 0 on success, negative error code on failure
195+
* @return NSAPI_ERROR_OK on success, negative error code on failure
196196
*/
197197
virtual nsapi_error_t socket_close(nsapi_socket_t handle) = 0;
198198

@@ -203,7 +203,7 @@ class NetworkStack: public DNS {
203203
*
204204
* @param handle Socket handle
205205
* @param address Local address to bind
206-
* @return 0 on success, negative error code on failure.
206+
* @return NSAPI_ERROR_OK on success, negative error code on failure.
207207
*/
208208
virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address) = 0;
209209

@@ -215,7 +215,7 @@ class NetworkStack: public DNS {
215215
* @param handle Socket handle
216216
* @param backlog Number of pending connections that can be queued
217217
* simultaneously
218-
* @return 0 on success, negative error code on failure
218+
* @return NSAPI_ERROR_OK on success, negative error code on failure
219219
*/
220220
virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog) = 0;
221221

@@ -226,7 +226,7 @@ class NetworkStack: public DNS {
226226
*
227227
* @param handle Socket handle
228228
* @param address The SocketAddress of the remote host
229-
* @return 0 on success, negative error code on failure
229+
* @return NSAPI_ERROR_OK on success, negative error code on failure
230230
*/
231231
virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address) = 0;
232232

@@ -246,7 +246,7 @@ class NetworkStack: public DNS {
246246
* @param server Socket handle to server to accept from
247247
* @param handle Destination for a handle to the newly created socket
248248
* @param address Destination for the remote address or NULL
249-
* @return 0 on success, negative error code on failure
249+
* @return NSAPI_ERROR_OK on success, negative error code on failure
250250
*/
251251
virtual nsapi_error_t socket_accept(nsapi_socket_t server,
252252
nsapi_socket_t *handle, SocketAddress *address = 0) = 0;
@@ -347,7 +347,7 @@ class NetworkStack: public DNS {
347347
* @param optname Stack-specific option identifier
348348
* @param optval Option value
349349
* @param optlen Length of the option value
350-
* @return 0 on success, negative error code on failure
350+
* @return NSAPI_ERROR_OK on success, negative error code on failure
351351
*/
352352
virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
353353
int optname, const void *optval, unsigned optlen);
@@ -363,7 +363,7 @@ class NetworkStack: public DNS {
363363
* @param optname Stack-specific option identifier
364364
* @param optval Destination for option value
365365
* @param optlen Length of the option value
366-
* @return 0 on success, negative error code on failure
366+
* @return NSAPI_ERROR_OK on success, negative error code on failure
367367
*/
368368
virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level,
369369
int optname, void *optval, unsigned *optlen);
@@ -397,7 +397,7 @@ class NetworkStack: public DNS {
397397
*
398398
* @param delay Delay in milliseconds
399399
* @param func Callback to be called
400-
* @return 0 on success, negative error code on failure
400+
* @return NSAPI_ERROR_OK on success, negative error code on failure
401401
*/
402402
virtual nsapi_error_t call_in(int delay, mbed::Callback<void()> func);
403403
};

0 commit comments

Comments
 (0)