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