Skip to content

Commit b9d9842

Browse files
gekygeky
committed
Revisited documentation for NetworkInterface specific methods
1 parent d84f4be commit b9d9842

File tree

1 file changed

+173
-89
lines changed

1 file changed

+173
-89
lines changed

‎NetworkInterface.h

Lines changed: 173 additions & 89 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,11 @@
2121
#include "SocketAddress.h"
2222

2323

24-
/** Enum of standardized error codes
24+
/** Enum of standardized error codes
25+
*
26+
* Valid error codes have negative values and may
27+
* be returned by any network operation.
28+
*
2529
* @enum nsapi_error_t
2630
*/
2731
enum nsapi_error_t {
@@ -38,6 +42,10 @@ enum nsapi_error_t {
3842
};
3943

4044
/** Enum of socket protocols
45+
*
46+
* The socket protocol specifies a particular protocol to
47+
* be used with a newly created socket.
48+
*
4149
* @enum protocol_t
4250
*/
4351
enum nsapi_protocol_t {
@@ -55,53 +63,66 @@ enum nsapi_protocol_t {
5563

5664

5765
/** NetworkInterface class
58-
* Common interface that is shared between all hardware that
59-
* can connect to a network over IP.
66+
*
67+
* Common interface that is shared between hardware that
68+
* can connect to a network over IP. By implementing the
69+
* NetworkInterface, a network stack can be used as a target
70+
* for instantiating network sockets.
6071
*/
6172
class NetworkInterface
6273
{
6374
public:
6475
virtual ~NetworkInterface() {};
6576

6677
/** Get the internally stored IP address
78+
*
6779
* @return IP address of the interface or null if not yet connected
6880
*/
6981
virtual const char *get_ip_address() = 0;
7082

7183
/** Get the internally stored MAC address
84+
*
7285
* @return MAC address of the interface
7386
*/
7487
virtual const char *get_mac_address() = 0;
7588

76-
/** Get the current status of the interface
77-
* @return true if connected
78-
*/
79-
virtual bool is_connected() {
80-
return get_ip_address() != NULL;
81-
}
82-
83-
/** Looks up the specified host's IP address
89+
/** Translates a host name to an IP address
90+
*
91+
* The host name may be either a domain name or an IP address.
92+
* If no stack-specific DNS resolution is provided, the host name
93+
* will be resolve using a UDP socket on the stack.
94+
*
8495
* @param address Destination for the host SocketAddress
85-
* @param name Hostname to lookup
86-
* @return 0 on success, negative on failure
96+
* @param host Host name to lookup
97+
* @return 0 on success, negative error code on failure
8798
*/
88-
virtual int gethostbyname(SocketAddress *address, const char *name);
99+
virtual int gethostbyname(SocketAddress *address, const char *host);
89100

90-
/* Set stack options
91-
* @param level Option level
92-
* @param optname Option identifier
101+
/* Set stack-specific stack options
102+
*
103+
* The setstackopt allow an application to pass stack-specific hints
104+
* to the underlying stack. For unsupported options,
105+
* NSAPI_ERROR_UNSUPPORTED is returned and the stack is unmodified.
106+
*
107+
* @param level Stack-specific protocol level
108+
* @param optname Stack-specific option identifier
93109
* @param optval Option value
94110
* @param optlen Length of the option value
95-
* @return 0 on success, negative on failure
111+
* @return 0 on success, negative error code on failure
96112
*/
97113
virtual int setstackopt(int level, int optname, const void *optval, unsigned optlen);
98114

99-
/* Get stack options
100-
* @param level Option level
101-
* @param optname Option identifier
102-
* @param optval Buffer where to write option value
115+
/* Get stack-specific stack options
116+
*
117+
* The getstackopt allow an application to retrieve stack-specific hints
118+
* from the underlying stack. For unsupported options,
119+
* NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
120+
*
121+
* @param level Stack-specific protocol level
122+
* @param optname Stack-specific option identifier
123+
* @param optval Destination for option value
103124
* @param optlen Length of the option value
104-
* @return 0 on success, negative on failure
125+
* @return 0 on success, negative error code on failure
105126
*/
106127
virtual int getstackopt(int level, int optname, void *optval, unsigned *optlen);
107128

@@ -111,127 +132,190 @@ class NetworkInterface
111132
friend class TCPSocket;
112133
friend class TCPServer;
113134

114-
/** Open a socket
115-
* @param handle Handle in which to store new socket
116-
* @param proto Type of socket to open, NSAPI_TCP or NSAPI_UDP
117-
* @return 0 on success, negative on failure
135+
/** Opens a socket
136+
*
137+
* Creates a socket for communication and stores it in the specified
138+
* handle. The handle must be passed to following calls on the socket.
139+
*
140+
* A stack may have a finite number of sockets, in this case
141+
* NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
142+
*
143+
* @param handle Destination for the handle to a newly created socket
144+
* @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
145+
* @return 0 on success, negative error code on failure
118146
*/
119147
virtual int socket_open(void **handle, nsapi_protocol_t proto) = 0;
120148

121149
/** Close the socket
150+
*
151+
* Closes any open connection and deallocates any memory associated with
152+
* the socket.
153+
*
122154
* @param handle Socket handle
123-
* @return 0 on success, negative on failure
124-
* @note On failure, any memory associated with the socket must still
125-
* be cleaned up
155+
* @return 0 on success, negative error code on failure
126156
*/
127157
virtual int socket_close(void *handle) = 0;
128158

129-
/** Bind a server socket to a specific port
159+
/** Bind a specific address to a socket
160+
*
161+
* Binding a socket specifies the address and port on which to recieve
162+
* data. If the IP address is zeroed, only the port is bound.
163+
*
130164
* @param handle Socket handle
131-
* @param address Local address to listen for incoming connections on
132-
* @return 0 on success, negative on failure.
165+
* @param address Local address to bind
166+
* @return 0 on success, negative error code on failure.
133167
*/
134168
virtual int socket_bind(void *handle, const SocketAddress &address) = 0;
135169

136-
/** Start listening for incoming connections
170+
/** Listen for connections on a TCP socket
171+
*
172+
* Marks the socket as a passive socket that can be used to accept
173+
* incoming connections.
174+
*
137175
* @param handle Socket handle
138-
* @param backlog Number of pending connections that can be queued up at any
139-
* one time [Default: 1]
140-
* @return 0 on success, negative on failure
176+
* @param backlog Number of pending connections that can be queued
177+
* simultaneously, defaults to 1
178+
* @return 0 on success, negative error code on failure
141179
*/
142180
virtual int socket_listen(void *handle, int backlog) = 0;
143181

144-
/** Connects this TCP socket to the server
182+
/** Connects TCP socket to a remote host
183+
*
184+
* Initiates a connection to a remote server specified by the
185+
* indicated address.
186+
*
145187
* @param handle Socket handle
146-
* @param address SocketAddress to connect to
147-
* @return 0 on success, negative on failure
188+
* @param address The SocketAddress of the remote host
189+
* @return 0 on success, negative error code on failure
148190
*/
149191
virtual int socket_connect(void *handle, const SocketAddress &address) = 0;
150-
151-
/** Check if the socket is connected
152-
* @param handle Socket handle
153-
* @return true if connected, false otherwise
154-
*/
155-
virtual bool socket_is_connected(void *handle) = 0;
156192

157-
/** Accept a new connection.
158-
* @param handle Handle in which to store new socket
193+
/** Accepts a connection on a TCP socket
194+
*
195+
* The server socket must be bound and set to listen for connections.
196+
* On a new connection, creates a socket stores it in the specified
197+
* handle. The handle must be passed to following calls on the socket.
198+
*
199+
* A stack may have a finite number of sockets, in this case
200+
* NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
201+
*
202+
* This call is non-blocking. If accept would block,
203+
* NSAPI_ERROR_WOULD_BLOCK is returned immediately.
204+
*
205+
* @param handle Destination for a handle to the newly created sockey
159206
* @param server Socket handle to server to accept from
160-
* @return 0 on success, negative on failure
161-
* @note This call is not-blocking, if this call would block, must
162-
* immediately return NSAPI_ERROR_WOULD_WAIT
207+
* @return 0 on success, negative error code on failure
163208
*/
164209
virtual int socket_accept(void **handle, void *server) = 0;
165210

166-
/** Send data to the remote host
211+
/** Send data over a TCP socket
212+
*
213+
* The socket must be connected to a remote host. Returns the number of
214+
* bytes sent from the buffer.
215+
*
216+
* This call is non-blocking. If send would block,
217+
* NSAPI_ERROR_WOULD_BLOCK is returned immediately.
218+
*
167219
* @param handle Socket handle
168-
* @param data The buffer to send to the host
169-
* @param size The length of the buffer to send
170-
* @return Number of written bytes on success, negative on failure
171-
* @note This call is not-blocking, if this call would block, must
172-
* immediately return NSAPI_ERROR_WOULD_WAIT
220+
* @param data Buffer of data to send to the host
221+
* @param size Size of the buffer in bytes
222+
* @return Number of sent bytes on success, negative error
223+
* code on failure
173224
*/
174225
virtual int socket_send(void *handle, const void *data, unsigned size) = 0;
175226

176-
/** Receive data from the remote host
227+
/** Receive data over a TCP socket
228+
*
229+
* The socket must be connected to a remote host. Returns the number of
230+
* bytes received into the buffer.
231+
*
232+
* This call is non-blocking. If recv would block,
233+
* NSAPI_ERROR_WOULD_BLOCK is returned immediately.
234+
*
177235
* @param handle Socket handle
178-
* @param data The buffer in which to store the data received from the host
179-
* @param size The maximum length of the buffer
180-
* @return Number of received bytes on success, negative on failure
181-
* @note This call is not-blocking, if this call would block, must
182-
* immediately return NSAPI_ERROR_WOULD_WAIT
236+
* @param data Destination buffer for data received from the host
237+
* @param size Size of the buffer in bytes
238+
* @return Number of received bytes on success, negative error
239+
* code on failure
183240
*/
184241
virtual int socket_recv(void *handle, void *data, unsigned size) = 0;
185242

186-
/** Send a packet to a remote endpoint
243+
/** Send a packet over a UDP socket
244+
*
245+
* Sends data to the specified address. Returns the number of bytes
246+
* sent from the buffer.
247+
*
248+
* This call is non-blocking. If sendto would block,
249+
* NSAPI_ERROR_WOULD_BLOCK is returned immediately.
250+
*
187251
* @param handle Socket handle
188-
* @param address The remote SocketAddress
189-
* @param data The packet to be sent
190-
* @param size The length of the packet to be sent
191-
* @return the number of written bytes on success, negative on failure
192-
* @note This call is not-blocking, if this call would block, must
193-
* immediately return NSAPI_ERROR_WOULD_WAIT
252+
* @param address The SocketAddress of the remote host
253+
* @param data Buffer of data to send to the host
254+
* @param size Size of the buffer in bytes
255+
* @return Number of sent bytes on success, negative error
256+
* code on failure
194257
*/
195258
virtual int socket_sendto(void *handle, const SocketAddress &address, const void *data, unsigned size) = 0;
196259

197-
/** Receive a packet from a remote endpoint
260+
/** Receive a packet over a UDP socket
261+
*
262+
* Receives data and stores the source address in address if address
263+
* is not NULL. Returns the number of bytes received into the buffer.
264+
*
265+
* This call is non-blocking. If recvfrom would block,
266+
* NSAPI_ERROR_WOULD_BLOCK is returned immediately.
267+
*
198268
* @param handle Socket handle
199-
* @param address Destination for the remote SocketAddress or null
200-
* @param buffer The buffer for storing the incoming packet data
201-
* If a packet is too long to fit in the supplied buffer,
202-
* excess bytes are discarded
203-
* @param size The length of the buffer
204-
* @return the number of received bytes on success, negative on failure
205-
* @note This call is not-blocking, if this call would block, must
206-
* immediately return NSAPI_ERROR_WOULD_WAIT
269+
* @param address Destination for the source address or NULL
270+
* @param data Destination buffer for data received from the host
271+
* @param size Size of the buffer in bytes
272+
* @return Number of received bytes on success, negative error
273+
* code on failure
207274
*/
208275
virtual int socket_recvfrom(void *handle, SocketAddress *address, void *buffer, unsigned size) = 0;
209276

210277
/** Register a callback on state change of the socket
278+
*
279+
* The specified callback will be called on state changes such as when
280+
* the socket can recv/send/accept successfully and on when an error
281+
* occurs. The callback may also be called spuriously without reason.
282+
*
283+
* The callback may be called in an interrupt context and should not
284+
* perform expensive operations such as recv/send calls.
285+
*
211286
* @param handle Socket handle
212287
* @param callback Function to call on state change
213288
* @param data Argument to pass to callback
214-
* @note Callback may be called in an interrupt context.
215289
*/
216290
virtual void socket_attach(void *handle, void (*callback)(void *), void *data) = 0;
217291

218-
/* Set socket options
292+
/* Set stack-specific socked options
293+
*
294+
* The setsockopt allow an application to pass stack-specific hints
295+
* to the underlying stack. For unsupported options,
296+
* NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
297+
*
219298
* @param handle Socket handle
220-
* @param level Option level
221-
* @param optname Option identifier
299+
* @param level Stack-specific protocol level
300+
* @param optname Stack-specific option identifier
222301
* @param optval Option value
223302
* @param optlen Length of the option value
224-
* @return 0 on success, negative on failure
303+
* @return 0 on success, negative error code on failure
225304
*/
226305
virtual int setsockopt(void *handle, int level, int optname, const void *optval, unsigned optlen);
227306

228-
/* Get socket options
307+
/* Get stack-specific socket options
308+
*
309+
* The getstackopt allow an application to retrieve stack-specific hints
310+
* from the underlying stack. For unsupported options,
311+
* NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
312+
*
229313
* @param handle Socket handle
230-
* @param level Option level
231-
* @param optname Option identifier
232-
* @param optval Buffer where to write option value
314+
* @param level Stack-specific protocol level
315+
* @param optname Stack-specific option identifier
316+
* @param optval Destination for option value
233317
* @param optlen Length of the option value
234-
* @return 0 on success, negative on failure
318+
* @return 0 on success, negative error code on failure
235319
*/
236320
virtual int getsockopt(void *handle, int level, int optname, void *optval, unsigned *optlen);
237321
};

0 commit comments

Comments
 (0)