Mistake on this page?
Report an issue in GitHub or email us
NetworkStack.h
Go to the documentation of this file.
1 
2 /* NetworkStack
3  * Copyright (c) 2015 ARM Limited
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License");
6  * you may not use this file except in compliance with the License.
7  * You may obtain a copy of the License at
8  *
9  * http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17 
18 #ifndef NETWORK_STACK_H
19 #define NETWORK_STACK_H
20 
21 #include "nsapi_types.h"
24 #include "DNS.h"
25 
26 /** @file NetworkStack.h NetworkStack class */
27 /** @addtogroup netsocket
28  * @{ */
29 
30 // Predeclared classes
32 
33 /** NetworkStack class
34  *
35  * Common interface that is shared between hardware that
36  * can connect to a network over IP. By implementing the
37  * NetworkStack, a network stack can be used as a target
38  * for instantiating network sockets.
39  */
40 class NetworkStack: public DNS {
41 public:
42  virtual ~NetworkStack() {};
43 
44  /** Get the local IP address
45  *
46  * @return Null-terminated representation of the local IP address
47  * or null if not yet connected
48  */
49  virtual const char *get_ip_address();
50 
51  /** Get the IPv6 link local address
52  *
53  * @address SocketAddress representation of the link local IPv6 address
54  * @return NSAPI_ERROR_OK on success, negative error code on failure
55  */
57 
58  /** Get the local IP address on interface name
59  *
60  * @param interface_name Network interface_name
61  * @return Null-terminated representation of the local IP address
62  * or null if not yet connected
63  */
64  virtual const char *get_ip_address_if(const char *interface_name);
65 
66  /** Translates a hostname to an IP address with specific version
67  *
68  * The hostname may be either a domain name or an IP address. If the
69  * hostname is an IP address, no network transactions will be performed.
70  *
71  * If no stack-specific DNS resolution is provided, the hostname
72  * will be resolve using a UDP socket on the stack.
73  *
74  * @param host Hostname to resolve
75  * @param address Pointer to a SocketAddress to store the result.
76  * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
77  * version is chosen by the stack (defaults to NSAPI_UNSPEC)
78  * @param interface_name Network interface_name
79  * @return NSAPI_ERROR_OK on success, negative error code on failure
80  */
81  virtual nsapi_error_t gethostbyname(const char *host,
82  SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC, const char *interface_name = NULL);
83 
84  /** Hostname translation callback (asynchronous)
85  *
86  * Callback will be called after DNS resolution completes or a failure occurs.
87  *
88  * Callback should not take more than 10ms to execute, otherwise it might
89  * prevent underlying thread processing. A portable user of the callback
90  * should not make calls to network operations due to stack size limitations.
91  * The callback should not perform expensive operations such as socket recv/send
92  * calls or blocking operations.
93  *
94  * @param status NSAPI_ERROR_OK on success, negative error code on failure
95  * @param address On success, destination for the host SocketAddress
96  */
98 
99  /** Translates a hostname to an IP address (asynchronous)
100  *
101  * The hostname may be either a domain name or an IP address. If the
102  * hostname is an IP address, no network transactions will be performed.
103  *
104  * If no stack-specific DNS resolution is provided, the hostname
105  * will be resolve using a UDP socket on the stack.
106  *
107  * Call is non-blocking. Result of the DNS operation is returned by the callback.
108  * If this function returns failure, callback will not be called. In case result
109  * is success (IP address was found from DNS cache), callback will be called
110  * before function returns.
111  *
112  * @param host Hostname to resolve
113  * @param callback Callback that is called for result
114  * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
115  * version is chosen by the stack (defaults to NSAPI_UNSPEC)
116  * @param interface_name Network interface_name
117  * @return 0 on immediate success,
118  * negative error code on immediate failure or
119  * a positive unique id that represents the hostname translation operation
120  * and can be passed to cancel
121  */
122  virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback, nsapi_version_t version = NSAPI_UNSPEC,
123  const char *interface_name = NULL);
124 
125  /** Cancels asynchronous hostname translation
126  *
127  * When translation is cancelled, callback will not be called.
128  *
129  * @param id Unique id of the hostname translation operation
130  * @return NSAPI_ERROR_OK on success, negative error code on failure
131  */
133 
134  /** Add a domain name server to list of servers to query
135  *
136  * @param address Destination for the host address
137  * @param interface_name Network interface name
138  * @return NSAPI_ERROR_OK on success, negative error code on failure
139  */
140  virtual nsapi_error_t add_dns_server(const SocketAddress &address, const char *interface_name = NULL);
141 
142  /** Get a domain name server from a list of servers to query
143  *
144  * Returns a DNS server address for a index. If returns error no more
145  * DNS servers to read.
146  *
147  * @param index Index of the DNS server, starts from zero
148  * @param address Destination for the host address
149  * @param interface_name Network interface name
150  * @return NSAPI_ERROR_OK on success, negative error code on failure
151  */
152  virtual nsapi_error_t get_dns_server(int index, SocketAddress *address, const char *interface_name = NULL);
153 
154  /* Set stack options
155  *
156  * setstackopt allows an application to pass stack-specific options
157  * to the underlying stack using stack-specific level and option names,
158  * or to request generic options using levels from nsapi_stack_level_t.
159  *
160  * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
161  * and the stack is unmodified.
162  *
163  * @param level Stack-specific protocol level or nsapi_stack_level_t
164  * @param optname Level-specific option name
165  * @param optval Option value
166  * @param optlen Length of the option value
167  * @return NSAPI_ERROR_OK on success, negative error code on failure
168  */
169  virtual nsapi_error_t setstackopt(int level, int optname, const void *optval, unsigned optlen);
170 
171  /* Get stack options
172  *
173  * getstackopt allows an application to retrieve stack-specific options
174  * to the underlying stack using stack-specific level and option names,
175  * or to request generic options using levels from nsapi_stack_level_t.
176  *
177  * @param level Stack-specific protocol level or nsapi_stack_level_t
178  * @param optname Level-specific option name
179  * @param optval Destination for option value
180  * @param optlen Length of the option value
181  * @return NSAPI_ERROR_OK on success, negative error code on failure
182  */
183  virtual nsapi_error_t getstackopt(int level, int optname, void *optval, unsigned *optlen);
184 
185  /** Dynamic downcast to a OnboardNetworkStack */
187  {
188  return 0;
189  }
190 
191 protected:
192  friend class InternetSocket;
193  friend class UDPSocket;
194  friend class TCPSocket;
195  friend class TCPServer;
196 
197  /** Opens a socket
198  *
199  * Creates a network socket and stores it in the specified handle.
200  * The handle must be passed to following calls on the socket.
201  *
202  * A stack may have a finite number of sockets, in this case
203  * NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
204  *
205  * @param handle Destination for the handle to a newly created socket
206  * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
207  * @return NSAPI_ERROR_OK on success, negative error code on failure
208  */
209  virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto) = 0;
210 
211  /** Close the socket
212  *
213  * Closes any open connection and deallocates any memory associated
214  * with the socket.
215  *
216  * @param handle Socket handle
217  * @return NSAPI_ERROR_OK on success, negative error code on failure
218  */
219  virtual nsapi_error_t socket_close(nsapi_socket_t handle) = 0;
220 
221  /** Bind a specific address to a socket
222  *
223  * Binding a socket specifies the address and port on which to receive
224  * data. If the IP address is zeroed, only the port is bound.
225  *
226  * @param handle Socket handle
227  * @param address Local address to bind
228  * @return NSAPI_ERROR_OK on success, negative error code on failure.
229  */
230  virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address) = 0;
231 
232  /** Listen for connections on a TCP socket
233  *
234  * Marks the socket as a passive socket that can be used to accept
235  * incoming connections.
236  *
237  * @param handle Socket handle
238  * @param backlog Number of pending connections that can be queued
239  * simultaneously
240  * @return NSAPI_ERROR_OK on success, negative error code on failure
241  */
242  virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog) = 0;
243 
244  /** Connects TCP socket to a remote host
245  *
246  * Initiates a connection to a remote server specified by the
247  * indicated address.
248  *
249  * @param handle Socket handle
250  * @param address The SocketAddress of the remote host
251  * @return NSAPI_ERROR_OK on success, negative error code on failure
252  */
253  virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address) = 0;
254 
255  /** Accepts a connection on a TCP socket
256  *
257  * The server socket must be bound and set to listen for connections.
258  * On a new connection, creates a network socket and stores it in the
259  * specified handle. The handle must be passed to following calls on
260  * the socket.
261  *
262  * A stack may have a finite number of sockets, in this case
263  * NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
264  *
265  * This call is non-blocking. If accept would block,
266  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
267  *
268  * @param server Socket handle to server to accept from
269  * @param handle Destination for a handle to the newly created socket
270  * @param address Destination for the remote address or NULL
271  * @return NSAPI_ERROR_OK on success, negative error code on failure
272  */
274  nsapi_socket_t *handle, SocketAddress *address = 0) = 0;
275 
276  /** Send data over a TCP socket
277  *
278  * The socket must be connected to a remote host. Returns the number of
279  * bytes sent from the buffer.
280  *
281  * This call is non-blocking. If send would block,
282  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
283  *
284  * @param handle Socket handle
285  * @param data Buffer of data to send to the host
286  * @param size Size of the buffer in bytes
287  * @return Number of sent bytes on success, negative error
288  * code on failure
289  */
291  const void *data, nsapi_size_t size) = 0;
292 
293  /** Receive data over a TCP socket
294  *
295  * The socket must be connected to a remote host. Returns the number of
296  * bytes received into the buffer.
297  *
298  * This call is non-blocking. If recv would block,
299  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
300  *
301  * @param handle Socket handle
302  * @param data Destination buffer for data received from the host
303  * @param size Size of the buffer in bytes
304  * @return Number of received bytes on success, negative error
305  * code on failure
306  */
308  void *data, nsapi_size_t size) = 0;
309 
310  /** Send a packet over a UDP socket
311  *
312  * Sends data to the specified address. Returns the number of bytes
313  * sent from the buffer.
314  *
315  * This call is non-blocking. If sendto would block,
316  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
317  *
318  * @param handle Socket handle
319  * @param address The SocketAddress of the remote host
320  * @param data Buffer of data to send to the host
321  * @param size Size of the buffer in bytes
322  * @return Number of sent bytes on success, negative error
323  * code on failure
324  */
325  virtual nsapi_size_or_error_t socket_sendto(nsapi_socket_t handle, const SocketAddress &address,
326  const void *data, nsapi_size_t size) = 0;
327 
328  /** Receive a packet over a UDP socket
329  *
330  * Receives data and stores the source address in address if address
331  * is not NULL. Returns the number of bytes received into the buffer.
332  *
333  * This call is non-blocking. If recvfrom would block,
334  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
335  *
336  * @param handle Socket handle
337  * @param address Destination for the source address or NULL
338  * @param buffer Destination buffer for data received from the host
339  * @param size Size of the buffer in bytes
340  * @return Number of received bytes on success, negative error
341  * code on failure
342  */
344  void *buffer, nsapi_size_t size) = 0;
345 
346  /** Register a callback on state change of the socket
347  *
348  * The specified callback will be called on state changes such as when
349  * the socket can recv/send/accept successfully and on when an error
350  * occurs. The callback may also be called spuriously without reason.
351  *
352  * The callback may be called in an interrupt context and should not
353  * perform expensive operations such as recv/send calls.
354  *
355  * @param handle Socket handle
356  * @param callback Function to call on state change
357  * @param data Argument to pass to callback
358  */
359  virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), void *data) = 0;
360 
361  /** Set stack-specific socket options.
362  *
363  * The setsockopt allow an application to pass stack-specific hints
364  * to the underlying stack. For unsupported options,
365  * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
366  *
367  * @param handle Socket handle.
368  * @param level Stack-specific protocol level.
369  * @param optname Stack-specific option identifier.
370  * @param optval Option value.
371  * @param optlen Length of the option value.
372  * @return NSAPI_ERROR_OK on success, negative error code on failure.
373  */
374  virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
375  int optname, const void *optval, unsigned optlen);
376 
377  /** Get stack-specific socket options.
378  *
379  * The getstackopt allow an application to retrieve stack-specific hints
380  * from the underlying stack. For unsupported options,
381  * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
382  *
383  * @param handle Socket handle.
384  * @param level Stack-specific protocol level.
385  * @param optname Stack-specific option identifier.
386  * @param optval Destination for option value.
387  * @param optlen Length of the option value.
388  * @return NSAPI_ERROR_OK on success, negative error code on failure.
389  */
390  virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level,
391  int optname, void *optval, unsigned *optlen);
392 
393 private:
394 
395  /** Call in callback
396  *
397  * Callback is used to call the call in method of the network stack.
398  */
400 
401  /** Get a call in callback
402  *
403  * Get a call in callback from the network stack context.
404  *
405  * Callback should not take more than 10ms to execute, otherwise it might
406  * prevent underlying thread processing. A portable user of the callback
407  * should not make calls to network operations due to stack size limitations.
408  * The callback should not perform expensive operations such as socket recv/send
409  * calls or blocking operations.
410  *
411  * @return Call in callback
412  */
413  virtual call_in_callback_cb_t get_call_in_callback();
414 
415  /** Call a callback after a delay
416  *
417  * Call a callback from the network stack context after a delay. If function
418  * returns error callback will not be called.
419  *
420  * @param delay Delay in milliseconds
421  * @param func Callback to be called
422  * @return NSAPI_ERROR_OK on success, negative error code on failure
423  */
424  virtual nsapi_error_t call_in(int delay, mbed::Callback<void()> func);
425 };
426 
427 /** Convert a raw nsapi_stack_t object into a C++ NetworkStack object
428  *
429  * @param stack Reference to an object that can be converted to a stack
430  * - A raw nsapi_stack_t object
431  * - A reference to a network stack
432  * - A reference to a network interface
433  * @return Reference to the underlying network stack
434  */
437 
438 template <typename IF>
440 {
441  return nsapi_create_stack(static_cast<NetworkInterface *>(iface)->get_stack());
442 }
443 
444 
445 #endif
446 
447 /** @} */
virtual nsapi_size_or_error_t socket_send(nsapi_socket_t handle, const void *data, nsapi_size_t size)=0
Send data over a TCP socket.
Socket implementation that uses IP network stack.
Base class for DNS provider.
Definition: DNS.h:25
SocketAddress class.
nsapi_stack structure
Definition: nsapi_types.h:304
NetworkStack * nsapi_create_stack(nsapi_stack_t *stack)
Convert a raw nsapi_stack_t object into a C++ NetworkStack object.
virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address)=0
Connects TCP socket to a remote host.
virtual const char * get_ip_address()
Get the local IP address.
virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog)=0
Listen for connections on a TCP socket.
NetworkStack class.
Definition: NetworkStack.h:40
Network Interface base class.
void * nsapi_socket_t
Opaque handle for network sockets.
Definition: nsapi_types.h:205
UDP socket implementation.
Definition: UDPSocket.h:31
TCP socket server.
Definition: TCPServer.h:32
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:95
virtual nsapi_error_t get_ipv6_link_local_address(SocketAddress *address)
Get the IPv6 link local address.
virtual OnboardNetworkStack * onboardNetworkStack()
Dynamic downcast to a OnboardNetworkStack.
Definition: NetworkStack.h:186
virtual nsapi_size_or_error_t socket_recv(nsapi_socket_t handle, void *data, nsapi_size_t size)=0
Receive data over a TCP socket.
virtual nsapi_error_t socket_close(nsapi_socket_t handle)=0
Close the socket.
virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address)=0
Bind a specific address to a socket.
virtual nsapi_size_or_error_t socket_recvfrom(nsapi_socket_t handle, SocketAddress *address, void *buffer, nsapi_size_t size)=0
Receive a packet over a UDP socket.
signed int nsapi_size_or_error_t
Type used to represent either a size or error passed through sockets.
Definition: nsapi_types.h:106
mbed OS API for onboard IP stack abstraction
virtual nsapi_error_t gethostbyname_async_cancel(int id)
Cancels asynchronous hostname translation.
mbed::Callback< void(nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t
Hostname translation callback (asynchronous)
Definition: NetworkStack.h:97
signed int nsapi_value_or_error_t
Type used to represent either a value or error.
Definition: nsapi_types.h:113
virtual nsapi_size_or_error_t socket_sendto(nsapi_socket_t handle, const SocketAddress &address, const void *data, nsapi_size_t size)=0
Send a packet over a UDP socket.
virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto)=0
Opens a socket.
virtual const char * get_ip_address_if(const char *interface_name)
Get the local IP address on interface name.
virtual nsapi_error_t get_dns_server(int index, SocketAddress *address, const char *interface_name=NULL)
Get a domain name server from a list of servers to query.
virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level, int optname, const void *optval, unsigned optlen)
Set stack-specific socket options.
SocketAddress class.
Definition: SocketAddress.h:35
TCP socket connection.
Definition: TCPSocket.h:32
virtual nsapi_error_t add_dns_server(const SocketAddress &address, const char *interface_name=NULL)
Add a domain name server to list of servers to query.
virtual void socket_attach(nsapi_socket_t handle, void(*callback)(void *), void *data)=0
Register a callback on state change of the socket.
virtual nsapi_error_t gethostbyname(const char *host, SocketAddress *address, nsapi_version_t version=NSAPI_UNSPEC, const char *interface_name=NULL)
Translates a hostname to an IP address with specific version.
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=0)
Create a callback class with type inferred from the arguments.
Definition: Callback.h:709
unsigned int nsapi_size_t
Type used to represent the size of data passed through sockets.
Definition: nsapi_types.h:99
virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, int optname, void *optval, unsigned *optlen)
Get stack-specific socket options.
virtual nsapi_error_t socket_accept(nsapi_socket_t server, nsapi_socket_t *handle, SocketAddress *address=0)=0
Accepts a connection on a TCP socket.
Callback class based on template specialization.
Definition: Callback.h:39
virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback, nsapi_version_t version=NSAPI_UNSPEC, const char *interface_name=NULL)
Translates a hostname to an IP address (asynchronous)
Domain Name Service.
Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.