Mistake on this page?
Report an issue in GitHub or email us
Nanostack.h
1 /*
2  * Copyright (c) 2016-2017, Arm Limited and affiliates.
3  * SPDX-License-Identifier: Apache-2.0
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 NANOSTACK_H_
19 #define NANOSTACK_H_
20 
21 #include "OnboardNetworkStack.h"
22 #include "NanostackMemoryManager.h"
23 #include "MeshInterface.h"
24 #include "mesh_interface_types.h"
25 #include "eventOS_event.h"
26 
27 struct ns_address;
28 
29 class Nanostack : public OnboardNetworkStack, private mbed::NonCopyable<Nanostack> {
30 public:
31  static Nanostack &get_instance();
32 
33  // Our Nanostack::Interface etc are defined by mbed_mesh_api
34  class Interface;
35  class EthernetInterface;
36  class MeshInterface;
37  class LoWPANNDInterface;
38  class ThreadInterface;
39  class WisunInterface;
40  class PPPInterface;
41 
42  /* Implement OnboardNetworkStack method */
43  nsapi_error_t add_ethernet_interface(EMAC &emac, bool default_if, OnboardNetworkStack::Interface **interface_out, NetworkInterface *user_network_interface = NULL) override;
44  nsapi_error_t add_ethernet_interface(EMAC &emac, bool default_if, OnboardNetworkStack::Interface **interface_out, const uint8_t *mac_addr, NetworkInterface *user_network_interface = NULL) override;
45 
46  /* Local variant with stronger typing and manual address specification */
47  nsapi_error_t add_ethernet_interface(EMAC &emac, bool default_if, Nanostack::EthernetInterface **interface_out, const uint8_t *mac_addr = NULL, NetworkInterface *user_network_interface = NULL);
48 
49  nsapi_error_t add_ppp_interface(PPP &ppp, bool default_if, OnboardNetworkStack::Interface **interface_out) override;
50 
51  /* Local variant with stronger typing and manual address specification */
52  nsapi_error_t add_ppp_interface(PPP &ppp, bool default_if, Nanostack::PPPInterface **interface_out);
53 
54  nsapi_error_t remove_ppp_interface(OnboardNetworkStack::Interface **interface_out) override;
55 
56 protected:
57 
58  Nanostack();
59 
60  /** @copydoc NetworkStack::get_ip_address */
61  nsapi_error_t get_ip_address(SocketAddress *sockAddr) override;
62 
63  /** Translate a hostname to an IP address with specific version using network interface name.
64  *
65  * The hostname may be either a domain name or an IP address. If the
66  * hostname is an IP address, no network transactions will be performed.
67  *
68  * Method first checks Nanostack DNS query result cache. If match is found, then the result is returned immediately.
69  * Otherwise method calls DNS resolver to find a match.
70  *
71  * @param host Hostname to resolve.
72  * @param address Pointer to a SocketAddress to store the result.
73  * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
74  * version is chosen by the stack (defaults to NSAPI_UNSPEC).
75  * @param interface_name Network interface name
76  * @return NSAPI_ERROR_OK on success, negative error code on failure.
77  */
78  virtual nsapi_error_t gethostbyname(const char *name, SocketAddress *address, nsapi_version_t version, const char *interface_name) override;
79 
80  /** Translate a hostname to an IP address (asynchronous) using network interface name.
81  *
82  * The hostname may be either a domain name or a dotted IP address. If the
83  * hostname is an IP address, no network transactions will be performed.
84  *
85  * Method first checks Nanostack DNS query result cache. If match is found, then the result is returned immediately.
86  *
87  * Call is non-blocking. Result of the DNS operation is returned by the callback.
88  * If this function returns failure, callback will not be called. In case result
89  * is success (IP address was found from DNS cache), callback will be called
90  * before function returns.
91  *
92  * @param host Hostname to resolve.
93  * @param callback Callback that is called for result.
94  * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
95  * version is chosen by the stack (defaults to NSAPI_UNSPEC).
96  * @param interface_name Network interface name
97  * @return 0 on immediate success,
98  * negative error code on immediate failure or
99  * a positive unique id that represents the hostname translation operation
100  * and can be passed to cancel.
101  */
102  virtual nsapi_value_or_error_t gethostbyname_async(const char *name, hostbyname_cb_t callback, nsapi_version_t version, const char *interface_name) override;
103 
104  /** Get a domain name server from a list of servers to query
105  *
106  * Returns a DNS server address for a index. DNS servers are queried from Nanostack DNS cache.
107  * If returns error no more DNS servers to read.
108  *
109  * @param index Index of the DNS server, starts from zero
110  * @param address Destination for the host address
111  * @param interface_name Network interface name
112  * @return 0 on success, negative error code on failure
113  */
114  virtual nsapi_error_t get_dns_server(int index, SocketAddress *address, const char *interface_name) override;
115 
116  /** Opens a socket
117  *
118  * Creates a network socket and stores it in the specified handle.
119  * The handle must be passed to following calls on the socket.
120  *
121  * A stack may have a finite number of sockets, in this case
122  * NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
123  *
124  * @param handle Destination for the handle to a newly created socket
125  * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
126  * @return 0 on success, negative error code on failure
127  */
128  nsapi_error_t socket_open(void **handle, nsapi_protocol_t proto) override;
129 
130  /** Close the socket
131  *
132  * Closes any open connection and deallocates any memory associated
133  * with the socket.
134  *
135  * @param handle Socket handle
136  * @return 0 on success, negative error code on failure
137  */
138  nsapi_error_t socket_close(void *handle) override;
139 
140  /** Bind a specific address to a socket
141  *
142  * Binding a socket specifies the address and port on which to recieve
143  * data. If the IP address is zeroed, only the port is bound.
144  *
145  * @param handle Socket handle
146  * @param address Local address to bind
147  * @return 0 on success, negative error code on failure.
148  */
149  nsapi_error_t socket_bind(void *handle, const SocketAddress &address) override;
150 
151  /** Listen for connections on a TCP socket
152  *
153  * Marks the socket as a passive socket that can be used to accept
154  * incoming connections.
155  *
156  * @param handle Socket handle
157  * @param backlog Number of pending connections that can be queued
158  * simultaneously
159  * @return 0 on success, negative error code on failure
160  */
161  nsapi_error_t socket_listen(void *handle, int backlog) override;
162 
163  /** Connects TCP socket to a remote host
164  *
165  * Initiates a connection to a remote server specified by the
166  * indicated address.
167  *
168  * @param handle Socket handle
169  * @param address The SocketAddress of the remote host
170  * @return 0 on success, negative error code on failure
171  */
172  nsapi_error_t socket_connect(void *handle, const SocketAddress &address) override;
173 
174  /** Accepts a connection on a TCP socket
175  *
176  * The server socket must be bound and set to listen for connections.
177  * On a new connection, creates a network socket and stores it in the
178  * specified handle. The handle must be passed to following calls on
179  * the socket.
180  *
181  * A stack may have a finite number of sockets, in this case
182  * NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
183  *
184  * This call is non-blocking. If accept would block,
185  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
186  *
187  * @param server Socket handle to server to accept from
188  * @param handle Destination for a handle to the newly created socket
189  * @param address Destination for the remote address or NULL
190  * @return 0 on success, negative error code on failure
191  */
192  nsapi_error_t socket_accept(void *handle, void **server, SocketAddress *address) override;
193 
194  /** Send data over a TCP socket
195  *
196  * The socket must be connected to a remote host. Returns the number of
197  * bytes sent from the buffer.
198  *
199  * This call is non-blocking. If send would block,
200  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
201  *
202  * @param handle Socket handle
203  * @param data Buffer of data to send to the host
204  * @param size Size of the buffer in bytes
205  * @return Number of sent bytes on success, negative error
206  * code on failure
207  */
208  nsapi_size_or_error_t socket_send(void *handle, const void *data, nsapi_size_t size) override;
209 
210  /** Receive data over a TCP socket
211  *
212  * The socket must be connected to a remote host. Returns the number of
213  * bytes received into the buffer.
214  *
215  * This call is non-blocking. If recv would block,
216  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
217  *
218  * @param handle Socket handle
219  * @param data Destination buffer for data received from the host
220  * @param size Size of the buffer in bytes
221  * @return Number of received bytes on success, negative error
222  * code on failure
223  */
224  nsapi_size_or_error_t socket_recv(void *handle, void *data, nsapi_size_t size) override;
225 
226  /** Send a packet over a UDP socket
227  *
228  * Sends data to the specified address. Returns the number of bytes
229  * sent from the buffer.
230  *
231  * This call is non-blocking. If sendto would block,
232  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
233  *
234  * @param handle Socket handle
235  * @param address The SocketAddress of the remote host
236  * @param data Buffer of data to send to the host
237  * @param size Size of the buffer in bytes
238  * @return Number of sent bytes on success, negative error
239  * code on failure
240  */
241  nsapi_size_or_error_t socket_sendto(void *handle, const SocketAddress &address, const void *data, nsapi_size_t size) override;
242 
243  /** Receive a packet over a UDP socket
244  *
245  * Receives data and stores the source address in address if address
246  * is not NULL. Returns the number of bytes received into the buffer.
247  *
248  * This call is non-blocking. If recvfrom would block,
249  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
250  *
251  * @param handle Socket handle
252  * @param address Destination for the source address or NULL
253  * @param buffer Destination buffer for data received from the host
254  * @param size Size of the buffer in bytes
255  * @return Number of received bytes on success, negative error
256  * code on failure
257  */
258  nsapi_size_or_error_t socket_recvfrom(void *handle, SocketAddress *address, void *buffer, nsapi_size_t size) override;
259 
260  /** Register a callback on state change of the socket
261  *
262  * The specified callback will be called on state changes such as when
263  * the socket can recv/send/accept successfully and on when an error
264  * occurs. The callback may also be called spuriously without reason.
265  *
266  * The callback may be called in an interrupt context and should not
267  * perform expensive operations such as recv/send calls.
268  *
269  * @param handle Socket handle
270  * @param callback Function to call on state change
271  * @param data Argument to pass to callback
272  */
273  void socket_attach(void *handle, void (*callback)(void *), void *data) override;
274 
275  /* Set stack-specific socket options
276  *
277  * The setsockopt allow an application to pass stack-specific hints
278  * to the underlying stack. For unsupported options,
279  * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
280  *
281  * @param handle Socket handle
282  * @param level Stack-specific protocol level
283  * @param optname Stack-specific option identifier
284  * @param optval Option value
285  * @param optlen Length of the option value
286  * @return 0 on success, negative error code on failure
287  */
288  nsapi_error_t setsockopt(void *handle, int level, int optname, const void *optval, unsigned optlen) override;
289 
290  /* Get stack-specific socket options
291  *
292  * The getstackopt allow an application to retrieve stack-specific hints
293  * from the underlying stack. For unsupported options,
294  * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
295  *
296  * @param handle Socket handle
297  * @param level Stack-specific protocol level
298  * @param optname Stack-specific option identifier
299  * @param optval Destination for option value
300  * @param optlen Length of the option value
301  * @return 0 on success, negative error code on failure
302  */
303  nsapi_error_t getsockopt(void *handle, int level, int optname, void *optval, unsigned *optlen) override;
304 
305 private:
306 
307  /** Call in callback
308  *
309  * Callback is used to call the call in method of the network stack.
310  */
312 
313  /** Get a call in callback
314  *
315  * Get a call in callback from the network stack context.
316  *
317  * Callback should not take more than 10ms to execute, otherwise it might
318  * prevent underlying thread processing. A portable user of the callback
319  * should not make calls to network operations due to stack size limitations.
320  * The callback should not perform expensive operations such as socket recv/send
321  * calls or blocking operations.
322  *
323  * @return Call in callback
324  */
325  call_in_callback_cb_t get_call_in_callback() override;
326 
327  /** Call a callback after a delay
328  *
329  * Call a callback from the network stack context after a delay. If function
330  * returns error callback will not be called.
331  *
332  * @param delay Delay in milliseconds
333  * @param func Callback to be called
334  * @return 0 on success, negative error code on failure
335  */
336  nsapi_error_t call_in(int delay, mbed::Callback<void()> func) override;
337 
338  struct nanostack_callback {
340  };
341 
342  nsapi_size_or_error_t do_sendto(void *handle, const struct ns_address *address, const void *data, nsapi_size_t size);
343  static void call_event_tasklet_main(arm_event_s *event);
344  char text_ip_address[40];
345  NanostackMemoryManager memory_manager;
346  int8_t call_event_tasklet;
347 };
348 
349 nsapi_error_t map_mesh_error(mesh_error_t err);
350 
351 #endif /* NANOSTACK_H_ */
nsapi_size_or_error_t socket_recvfrom(void *handle, SocketAddress *address, void *buffer, nsapi_size_t size) override
Receive a packet over a UDP socket.
Wi-SUN mesh network interface class.
virtual nsapi_value_or_error_t gethostbyname_async(const char *name, hostbyname_cb_t callback, nsapi_version_t version, const char *interface_name) override
Translate a hostname to an IP address (asynchronous) using network interface name.
6LoWPAN-ND mesh network interface class
nsapi_error_t setsockopt(void *handle, int level, int optname, const void *optval, unsigned optlen) override
Set stack-specific socket options.
nsapi_error_t socket_bind(void *handle, const SocketAddress &address) override
Bind a specific address to a socket.
Representation of a stack&#39;s view of an interface.
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:142
nsapi_error_t getsockopt(void *handle, int level, int optname, void *optval, unsigned *optlen) override
Get stack-specific socket options.
Prevents generation of copy constructor and copy assignment operator in derived classes.
Definition: NonCopyable.h:162
Callback< R(ArgTs...)> callback(R(*func)(ArgTs...)=nullptr) noexcept
Create a callback class with type inferred from the arguments.
Definition: Callback.h:678
signed int nsapi_size_or_error_t
Type used to represent either a size or error passed through sockets.
Definition: nsapi_types.h:153
nsapi_size_or_error_t socket_recv(void *handle, void *data, nsapi_size_t size) override
Receive data over a TCP socket.
nsapi_error_t socket_listen(void *handle, int backlog) override
Listen for connections on a TCP socket.
Thread mesh network interface class.
mbed OS API for onboard IP stack abstraction
signed int nsapi_value_or_error_t
Type used to represent either a value or error.
Definition: nsapi_types.h:160
Definition: PPP.h:26
nsapi_error_t socket_open(void **handle, nsapi_protocol_t proto) override
Opens a socket.
SocketAddress class.
Definition: SocketAddress.h:37
Common interface that is shared between network devices.
nsapi_size_or_error_t socket_send(void *handle, const void *data, nsapi_size_t size) override
Send data over a TCP socket.
nsapi_error_t get_ip_address(SocketAddress *sockAddr) override
Get the local IP address.
nsapi_size_or_error_t socket_sendto(void *handle, const SocketAddress &address, const void *data, nsapi_size_t size) override
Send a packet over a UDP socket.
nsapi_error_t socket_close(void *handle) override
Close the socket.
virtual nsapi_error_t get_dns_server(int index, SocketAddress *address, const char *interface_name) override
Get a domain name server from a list of servers to query.
virtual nsapi_error_t gethostbyname(const char *name, SocketAddress *address, nsapi_version_t version, const char *interface_name) override
Translate a hostname to an IP address with specific version using network interface name...
nsapi_error_t add_ethernet_interface(EMAC &emac, bool default_if, OnboardNetworkStack::Interface **interface_out, NetworkInterface *user_network_interface=NULL) override
Register a network interface with the IP stack.
unsigned int nsapi_size_t
Type used to represent the size of data passed through sockets.
Definition: nsapi_types.h:146
This interface should be used to abstract low level access to networking hardware All operations rece...
Definition: EMAC.h:33
void socket_attach(void *handle, void(*callback)(void *), void *data) override
Register a callback on state change of the socket.
nsapi_error_t socket_accept(void *handle, void **server, SocketAddress *address) override
Accepts a connection on a TCP socket.
Callback class based on template specialization.
Definition: Callback.h:53
nsapi_error_t socket_connect(void *handle, const SocketAddress &address) override
Connects TCP socket to a remote host.
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.