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  * @param address SocketAddress representation of the local IP address
47  * @retval NSAPI_ERROR_OK on success
48  * @retval NSAPI_ERROR_UNSUPPORTED if this feature is not supported
49  * @retval NSAPI_ERROR_PARAMETER if the provided pointer is invalid
50  * @retval NSAPI_ERROR_NO_ADDRESS if the address cannot be obtained from stack
51  */
52  virtual nsapi_error_t get_ip_address(SocketAddress *address);
53 
54  MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
55  virtual const char *get_ip_address();
56 
57  /** Get the IPv6 link local address
58  *
59  * @param address SocketAddress representation of the link local IPv6 address
60  * @retval NSAPI_ERROR_OK on success
61  * @retval NSAPI_ERROR_UNSUPPORTED if this feature is not supported
62  * @retval NSAPI_ERROR_PARAMETER if the provided pointer is invalid
63  */
65 
66  /** Get the local IP address on interface name
67  *
68  * @param address SocketAddress representation of the link local IPv6 address
69  * @param interface_name Network interface_name
70  * @retval NSAPI_ERROR_OK on success
71  * @retval NSAPI_ERROR_UNSUPPORTED if this feature is not supported
72  * @retval NSAPI_ERROR_PARAMETER if the provided pointer is invalid
73  * @retval NSAPI_ERROR_NO_ADDRESS if the address cannot be obtained from stack
74  */
75  virtual nsapi_error_t get_ip_address_if(SocketAddress *address, const char *interface_name);
76 
77  MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
78  virtual const char *get_ip_address_if(const char *interface_name);
79 
80  /** Translates a hostname to an IP address with specific version
81  *
82  * The hostname may be either a domain name or an IP address. If the
83  * hostname is an IP address, no network transactions will be performed.
84  *
85  * If no stack-specific DNS resolution is provided, the hostname
86  * will be resolve using a UDP socket on the stack.
87  *
88  * @param host Hostname to resolve
89  * @param address Pointer to a SocketAddress to store the result.
90  * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
91  * version is chosen by the stack (defaults to NSAPI_UNSPEC)
92  * @param interface_name Network interface_name
93  * @return NSAPI_ERROR_OK on success, negative error code on failure
94  */
95  virtual nsapi_error_t gethostbyname(const char *host,
96  SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC, const char *interface_name = NULL);
97 
98  /** Hostname translation callback (asynchronous)
99  *
100  * Callback will be called after DNS resolution completes or a failure occurs.
101  *
102  * Callback should not take more than 10ms to execute, otherwise it might
103  * prevent underlying thread processing. A portable user of the callback
104  * should not make calls to network operations due to stack size limitations.
105  * The callback should not perform expensive operations such as socket recv/send
106  * calls or blocking operations.
107  *
108  * @param status NSAPI_ERROR_OK on success, negative error code on failure
109  * @param address On success, destination for the host SocketAddress
110  */
112 
113  /** Translates a hostname to an IP address (asynchronous)
114  *
115  * The hostname may be either a domain name or an IP address. If the
116  * hostname is an IP address, no network transactions will be performed.
117  *
118  * If no stack-specific DNS resolution is provided, the hostname
119  * will be resolve using a UDP socket on the stack.
120  *
121  * Call is non-blocking. Result of the DNS operation is returned by the callback.
122  * If this function returns failure, callback will not be called. In case result
123  * is success (IP address was found from DNS cache), callback will be called
124  * before function returns.
125  *
126  * @param host Hostname to resolve
127  * @param callback Callback that is called for result
128  * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
129  * version is chosen by the stack (defaults to NSAPI_UNSPEC)
130  * @param interface_name Network interface_name
131  * @return 0 on immediate success,
132  * negative error code on immediate failure or
133  * a positive unique id that represents the hostname translation operation
134  * and can be passed to cancel
135  */
136  virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback, nsapi_version_t version = NSAPI_UNSPEC,
137  const char *interface_name = NULL);
138 
139  /** Cancels asynchronous hostname translation
140  *
141  * When translation is cancelled, callback will not be called.
142  *
143  * @param id Unique id of the hostname translation operation
144  * @return NSAPI_ERROR_OK on success, negative error code on failure
145  */
147 
148  /** Add a domain name server to list of servers to query
149  *
150  * @param address Destination for the host address
151  * @param interface_name Network interface name
152  * @return NSAPI_ERROR_OK on success, negative error code on failure
153  */
154  virtual nsapi_error_t add_dns_server(const SocketAddress &address, const char *interface_name = NULL);
155 
156  /** Get a domain name server from a list of servers to query
157  *
158  * Returns a DNS server address for a index. If returns error no more
159  * DNS servers to read.
160  *
161  * @param index Index of the DNS server, starts from zero
162  * @param address Destination for the host address
163  * @param interface_name Network interface name
164  * @return NSAPI_ERROR_OK on success, negative error code on failure
165  */
166  virtual nsapi_error_t get_dns_server(int index, SocketAddress *address, const char *interface_name = NULL);
167 
168  /* Set stack options
169  *
170  * setstackopt allows an application to pass stack-specific options
171  * to the underlying stack using stack-specific level and option names,
172  * or to request generic options using levels from nsapi_stack_level_t.
173  *
174  * For unsupported options, NSAPI_ERROR_UNSUPPORTED is returned
175  * and the stack is unmodified.
176  *
177  * @param level Stack-specific protocol level or nsapi_stack_level_t
178  * @param optname Level-specific option name
179  * @param optval 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 setstackopt(int level, int optname, const void *optval, unsigned optlen);
184 
185  /* Get stack options
186  *
187  * getstackopt allows an application to retrieve stack-specific options
188  * to the underlying stack using stack-specific level and option names,
189  * or to request generic options using levels from nsapi_stack_level_t.
190  *
191  * @param level Stack-specific protocol level or nsapi_stack_level_t
192  * @param optname Level-specific option name
193  * @param optval Destination for option value
194  * @param optlen Length of the option value
195  * @return NSAPI_ERROR_OK on success, negative error code on failure
196  */
197  virtual nsapi_error_t getstackopt(int level, int optname, void *optval, unsigned *optlen);
198 
199  /** Dynamic downcast to a OnboardNetworkStack */
201  {
202  return 0;
203  }
204 
205 protected:
206  friend class InternetSocket;
207  friend class InternetDatagramSocket;
208  friend class TCPSocket;
209  friend class TCPServer;
210 
211  /** Opens a socket
212  *
213  * Creates a network socket and stores it in the specified handle.
214  * The handle must be passed to following calls on the socket.
215  *
216  * A stack may have a finite number of sockets, in this case
217  * NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
218  *
219  * @param handle Destination for the handle to a newly created socket
220  * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
221  * @return NSAPI_ERROR_OK on success, negative error code on failure
222  */
223  virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto) = 0;
224 
225  /** Close the socket
226  *
227  * Closes any open connection and deallocates any memory associated
228  * with the socket.
229  *
230  * @param handle Socket handle
231  * @return NSAPI_ERROR_OK on success, negative error code on failure
232  */
233  virtual nsapi_error_t socket_close(nsapi_socket_t handle) = 0;
234 
235  /** Bind a specific address to a socket
236  *
237  * Binding a socket specifies the address and port on which to receive
238  * data. If the IP address is zeroed, only the port is bound.
239  *
240  * @param handle Socket handle
241  * @param address Local address to bind
242  * @return NSAPI_ERROR_OK on success, negative error code on failure.
243  */
244  virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address) = 0;
245 
246  /** Listen for connections on a TCP socket
247  *
248  * Marks the socket as a passive socket that can be used to accept
249  * incoming connections.
250  *
251  * @param handle Socket handle
252  * @param backlog Number of pending connections that can be queued
253  * simultaneously
254  * @return NSAPI_ERROR_OK on success, negative error code on failure
255  */
256  virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog) = 0;
257 
258  /** Connects TCP socket to a remote host
259  *
260  * Initiates a connection to a remote server specified by the
261  * indicated address.
262  *
263  * @param handle Socket handle
264  * @param address The SocketAddress of the remote host
265  * @return NSAPI_ERROR_OK on success, negative error code on failure
266  */
267  virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address) = 0;
268 
269  /** Accepts a connection on a TCP socket
270  *
271  * The server socket must be bound and set to listen for connections.
272  * On a new connection, creates a network socket and stores it in the
273  * specified handle. The handle must be passed to following calls on
274  * the socket.
275  *
276  * A stack may have a finite number of sockets, in this case
277  * NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
278  *
279  * This call is non-blocking. If accept would block,
280  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
281  *
282  * @param server Socket handle to server to accept from
283  * @param handle Destination for a handle to the newly created socket
284  * @param address Destination for the remote address or NULL
285  * @return NSAPI_ERROR_OK on success, negative error code on failure
286  */
288  nsapi_socket_t *handle, SocketAddress *address = 0) = 0;
289 
290  /** Send data over a TCP socket
291  *
292  * The socket must be connected to a remote host. Returns the number of
293  * bytes sent from the buffer.
294  *
295  * This call is non-blocking. If send would block,
296  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
297  *
298  * @param handle Socket handle
299  * @param data Buffer of data to send to the host
300  * @param size Size of the buffer in bytes
301  * @return Number of sent bytes on success, negative error
302  * code on failure
303  */
305  const void *data, nsapi_size_t size) = 0;
306 
307  /** Receive data over a TCP socket
308  *
309  * The socket must be connected to a remote host. Returns the number of
310  * bytes received into the buffer.
311  *
312  * This call is non-blocking. If recv would block,
313  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
314  *
315  * @param handle Socket handle
316  * @param data Destination buffer for data received from the host
317  * @param size Size of the buffer in bytes
318  * @return Number of received bytes on success, negative error
319  * code on failure
320  */
322  void *data, nsapi_size_t size) = 0;
323 
324  /** Send a packet over a UDP socket
325  *
326  * Sends data to the specified address. Returns the number of bytes
327  * sent from the buffer.
328  *
329  * This call is non-blocking. If sendto would block,
330  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
331  *
332  * @param handle Socket handle
333  * @param address The SocketAddress of the remote host
334  * @param data Buffer of data to send to the host
335  * @param size Size of the buffer in bytes
336  * @return Number of sent bytes on success, negative error
337  * code on failure
338  */
339  virtual nsapi_size_or_error_t socket_sendto(nsapi_socket_t handle, const SocketAddress &address,
340  const void *data, nsapi_size_t size) = 0;
341 
342  /** Receive a packet over a UDP socket
343  *
344  * Receives data and stores the source address in address if address
345  * is not NULL. Returns the number of bytes received into the buffer.
346  *
347  * This call is non-blocking. If recvfrom would block,
348  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
349  *
350  * @param handle Socket handle
351  * @param address Destination for the source address or NULL
352  * @param buffer Destination buffer for data received from the host
353  * @param size Size of the buffer in bytes
354  * @return Number of received bytes on success, negative error
355  * code on failure
356  */
358  void *buffer, nsapi_size_t size) = 0;
359 
360  /** Register a callback on state change of the socket
361  *
362  * The specified callback will be called on state changes such as when
363  * the socket can recv/send/accept successfully and on when an error
364  * occurs. The callback may also be called spuriously without reason.
365  *
366  * The callback may be called in an interrupt context and should not
367  * perform expensive operations such as recv/send calls.
368  *
369  * @param handle Socket handle
370  * @param callback Function to call on state change
371  * @param data Argument to pass to callback
372  */
373  virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), void *data) = 0;
374 
375  /** Set stack-specific socket options.
376  *
377  * The setsockopt allow an application to pass stack-specific hints
378  * to the underlying stack. For unsupported options,
379  * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
380  *
381  * @param handle Socket handle.
382  * @param level Stack-specific protocol level.
383  * @param optname Stack-specific option identifier.
384  * @param optval Option value.
385  * @param optlen Length of the option value.
386  * @return NSAPI_ERROR_OK on success, negative error code on failure.
387  */
388  virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
389  int optname, const void *optval, unsigned optlen);
390 
391  /** Get stack-specific socket options.
392  *
393  * The getstackopt allow an application to retrieve stack-specific hints
394  * from the underlying stack. For unsupported options,
395  * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
396  *
397  * @param handle Socket handle.
398  * @param level Stack-specific protocol level.
399  * @param optname Stack-specific option identifier.
400  * @param optval Destination for option value.
401  * @param optlen Length of the option value.
402  * @return NSAPI_ERROR_OK on success, negative error code on failure.
403  */
404  virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level,
405  int optname, void *optval, unsigned *optlen);
406 
407 private:
408 
409  /** Call in callback
410  *
411  * Callback is used to call the call in method of the network stack.
412  */
414 
415  /** Get a call in callback
416  *
417  * Get a call in callback from the network stack context.
418  *
419  * Callback should not take more than 10ms to execute, otherwise it might
420  * prevent underlying thread processing. A portable user of the callback
421  * should not make calls to network operations due to stack size limitations.
422  * The callback should not perform expensive operations such as socket recv/send
423  * calls or blocking operations.
424  *
425  * @return Call in callback
426  */
427  virtual call_in_callback_cb_t get_call_in_callback();
428 
429  /** Call a callback after a delay
430  *
431  * Call a callback from the network stack context after a delay. If function
432  * returns error callback will not be called.
433  *
434  * @param delay Delay in milliseconds
435  * @param func Callback to be called
436  * @return NSAPI_ERROR_OK on success, negative error code on failure
437  */
438  virtual nsapi_error_t call_in(int delay, mbed::Callback<void()> func);
439 };
440 
441 /** Convert a raw nsapi_stack_t object into a C++ NetworkStack object
442  *
443  * @param stack Reference to an object that can be converted to a stack
444  * - A raw nsapi_stack_t object
445  * - A reference to a network stack
446  * - A reference to a network interface
447  * @return Reference to the underlying network stack
448  */
451 
452 template <typename IF>
454 {
455  return nsapi_create_stack(static_cast<NetworkInterface *>(iface)->get_stack());
456 }
457 
458 
459 #endif
460 
461 /** @} */
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:319
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 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
TCP socket server.
Definition: TCPServer.h:32
virtual nsapi_error_t get_ip_address(SocketAddress *address)
Get the local IP address.
virtual nsapi_error_t get_ip_address_if(SocketAddress *address, const char *interface_name)
Get the local IP address on interface name.
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:200
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:111
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 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)
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
InternetDatagramSocket socket implementation.
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.