Mistake on this page?
Report an issue in GitHub or email us
emac_TestNetworkStack.h
1 /*
2  * Copyright (c) 2018, ARM Limited, All Rights Reserved
3  * SPDX-License-Identifier: Apache-2.0
4  *
5  * Licensed under the Apache License, Version 2.0 (the "License"); you may
6  * 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, WITHOUT
13  * 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 EMAC_TEST_NETWORK_STACK_H
19 #define EMAC_TEST_NETWORK_STACK_H
20 
21 #include "netsocket/nsapi_types.h"
22 #include "netsocket/EMAC.h"
23 #include "netsocket/OnboardNetworkStack.h"
24 
25 #include "emac_TestMemoryManager.h"
26 
27 class EmacTestNetworkStack : public OnboardNetworkStack, private mbed::NonCopyable<EmacTestNetworkStack> {
28 public:
29 
30  static EmacTestNetworkStack &get_instance();
31 
33  virtual ~EmacTestNetworkStack() {}
34 
36  public:
37 
38  static Interface &get_instance();
39 
40  /** Connect the interface to the network
41  *
42  * Sets up a connection on specified network interface, using DHCP or provided network details. If the @a dhcp is set to
43  * true all the remaining parameters are ignored.
44  *
45  * @param dhcp true if the network details should be acquired using DHCP
46  * @param ip IP address to be used for the interface as "W:X:Y:Z" or NULL
47  * @param netmask Net mask to be used for the interface as "W:X:Y:Z" or NULL
48  * @param gw Gateway address to be used for the interface as "W:X:Y:Z" or NULL
49  * @param stack Allow manual selection of IPv4 and/or IPv6.
50  * @param blocking Specify whether bringup blocks for connection completion.
51  * @return NSAPI_ERROR_OK on success, or error code
52  */
53  virtual nsapi_error_t bringup(bool dhcp, const char *ip,
54  const char *netmask, const char *gw,
55  nsapi_ip_stack_t stack = DEFAULT_STACK,
56  bool blocking = true
57  );
58 
59  /** Disconnect interface from the network
60  *
61  * After this call the network interface is inactive, to use it again user needs to call @a mbed_ipstack_bringup again.
62  *
63  * @return NSAPI_ERROR_OK on success, or error code
64  */
65  virtual nsapi_error_t bringdown();
66 
67  /** Register callback for status reporting
68  *
69  * The specified status callback function will be called on status changes
70  * on the network. The parameters on the callback are the event type and
71  * event-type dependent reason parameter.
72  *
73  * @param status_cb The callback for status changes
74  */
75  virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
76 
77  /** Get the connection status
78  *
79  * @return The connection status according to ConnectionStatusType
80  */
81  virtual nsapi_connection_status_t get_connection_status() const;
82 
83  /** Return MAC address of the network interface
84  *
85  * @return MAC address as "V:W:X:Y:Z"
86  */
87  virtual char *get_mac_address(char *buf, nsapi_size_t buflen);
88 
89  /** Copies IP address of the network interface to user supplied buffer
90  *
91  * @param buf buffer to which IP address will be copied as "W:X:Y:Z"
92  * @param buflen size of supplied buffer
93  * @return Pointer to a buffer, or NULL if the buffer is too small
94  */
95  virtual nsapi_error_t get_ip_address(SocketAddress *address);
96 
97  MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
98  virtual char *get_ip_address(char *buf, nsapi_size_t buflen);
99 
100  /** Copies netmask of the network interface to user supplied buffer
101  *
102  * @param buf buffer to which netmask will be copied as "W:X:Y:Z"
103  * @param buflen size of supplied buffer
104  * @return Pointer to a buffer, or NULL if the buffer is too small
105  */
106  virtual nsapi_error_t get_netmask(SocketAddress *address);
107 
108  MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
109  virtual char *get_netmask(char *buf, nsapi_size_t buflen);
110 
111  /** Copies gateway address of the network interface to user supplied buffer
112  *
113  * @param buf buffer to which gateway address will be copied as "W:X:Y:Z"
114  * @param buflen size of supplied buffer
115  * @return Pointer to a buffer, or NULL if the buffer is too small
116  */
117  virtual nsapi_error_t get_gateway(SocketAddress *address);
118 
119  MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
120  virtual char *get_gateway(char *buf, nsapi_size_t buflen);
121 
122  private:
123  friend EmacTestNetworkStack;
124 
125  Interface();
126 
127  EMAC *m_emac;
128  };
129 
130  /** Register a network interface with the IP stack
131  *
132  * Connects EMAC layer with the IP stack and initializes all the required infrastructure.
133  * This function should be called only once for each available interface.
134  *
135  * @param emac EMAC HAL implementation for this network interface
136  * @param default_if true if the interface should be treated as the default one
137  * @param[out] interface_out pointer to stack interface object controlling the EMAC
138  * @return NSAPI_ERROR_OK on success, or error code
139  */
140  virtual nsapi_error_t add_ethernet_interface(EMAC &emac, bool default_if, OnboardNetworkStack::Interface **interface_out);
141 
142  /** Translates a hostname to an IP address with specific version
143  *
144  * The hostname may be either a domain name or an IP address. If the
145  * hostname is an IP address, no network transactions will be performed.
146  *
147  * If no stack-specific DNS resolution is provided, the hostname
148  * will be resolve using a UDP socket on the stack.
149  *
150  * @param host Hostname to resolve
151  * @param address Destination for the host SocketAddress
152  * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
153  * version is chosen by the stack (defaults to NSAPI_UNSPEC)
154  * @return 0 on success, negative error code on failure
155  */
156  virtual nsapi_error_t gethostbyname(const char *host,
157  SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC);
158 
159  /** Add a domain name server to list of servers to query
160  *
161  * @param address Destination for the host address
162  * @return 0 on success, negative error code on failure
163  */
164  virtual nsapi_error_t add_dns_server(const SocketAddress &address);
165 
166 protected:
167 
168  /** Opens a socket
169  *
170  * Creates a network socket and stores it in the specified handle.
171  * The handle must be passed to following calls on the socket.
172  *
173  * A stack may have a finite number of sockets, in this case
174  * NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
175  *
176  * @param handle Destination for the handle to a newly created socket
177  * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
178  * @return 0 on success, negative error code on failure
179  */
180  virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto);
181 
182  /** Close the socket
183  *
184  * Closes any open connection and deallocates any memory associated
185  * with the socket.
186  *
187  * @param handle Socket handle
188  * @return 0 on success, negative error code on failure
189  */
190  virtual nsapi_error_t socket_close(nsapi_socket_t handle);
191 
192  /** Bind a specific address to a socket
193  *
194  * Binding a socket specifies the address and port on which to receive
195  * data. If the IP address is zeroed, only the port is bound.
196  *
197  * @param handle Socket handle
198  * @param address Local address to bind
199  * @return 0 on success, negative error code on failure.
200  */
201  virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address);
202 
203  /** Listen for connections on a TCP socket
204  *
205  * Marks the socket as a passive socket that can be used to accept
206  * incoming connections.
207  *
208  * @param handle Socket handle
209  * @param backlog Number of pending connections that can be queued
210  * simultaneously
211  * @return 0 on success, negative error code on failure
212  */
213  virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog);
214 
215  /** Connects TCP socket to a remote host
216  *
217  * Initiates a connection to a remote server specified by the
218  * indicated address.
219  *
220  * @param handle Socket handle
221  * @param address The SocketAddress of the remote host
222  * @return 0 on success, negative error code on failure
223  */
224  virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address);
225 
226  /** Accepts a connection on a TCP socket
227  *
228  * The server socket must be bound and set to listen for connections.
229  * On a new connection, creates a network socket and stores it in the
230  * specified handle. The handle must be passed to following calls on
231  * the socket.
232  *
233  * A stack may have a finite number of sockets, in this case
234  * NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
235  *
236  * This call is non-blocking. If accept would block,
237  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
238  *
239  * @param server Socket handle to server to accept from
240  * @param handle Destination for a handle to the newly created socket
241  * @param address Destination for the remote address or NULL
242  * @return 0 on success, negative error code on failure
243  */
245  nsapi_socket_t *handle, SocketAddress *address = 0);
246 
247  /** Send data over a TCP socket
248  *
249  * The socket must be connected to a remote host. Returns the number of
250  * bytes sent from the buffer.
251  *
252  * This call is non-blocking. If send would block,
253  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
254  *
255  * @param handle Socket handle
256  * @param data Buffer of data to send to the host
257  * @param size Size of the buffer in bytes
258  * @return Number of sent bytes on success, negative error
259  * code on failure
260  */
262  const void *data, nsapi_size_t size);
263 
264  /** Receive data over a TCP socket
265  *
266  * The socket must be connected to a remote host. Returns the number of
267  * bytes received into the buffer.
268  *
269  * This call is non-blocking. If recv would block,
270  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
271  *
272  * @param handle Socket handle
273  * @param data Destination buffer for data received from the host
274  * @param size Size of the buffer in bytes
275  * @return Number of received bytes on success, negative error
276  * code on failure
277  */
279  void *data, nsapi_size_t size);
280 
281  /** Send a packet over a UDP socket
282  *
283  * Sends data to the specified address. Returns the number of bytes
284  * sent from the buffer.
285  *
286  * This call is non-blocking. If sendto would block,
287  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
288  *
289  * @param handle Socket handle
290  * @param address The SocketAddress of the remote host
291  * @param data Buffer of data to send to the host
292  * @param size Size of the buffer in bytes
293  * @return Number of sent bytes on success, negative error
294  * code on failure
295  */
296  virtual nsapi_size_or_error_t socket_sendto(nsapi_socket_t handle, const SocketAddress &address,
297  const void *data, nsapi_size_t size);
298 
299  /** Receive a packet over a UDP socket
300  *
301  * Receives data and stores the source address in address if address
302  * is not NULL. Returns the number of bytes received into the buffer.
303  *
304  * This call is non-blocking. If recvfrom would block,
305  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
306  *
307  * @param handle Socket handle
308  * @param address Destination for the source address or NULL
309  * @param buffer Destination buffer for data received from the host
310  * @param size Size of the buffer in bytes
311  * @return Number of received bytes on success, negative error
312  * code on failure
313  */
315  void *buffer, nsapi_size_t size);
316 
317  /** Register a callback on state change of the socket
318  *
319  * The specified callback will be called on state changes such as when
320  * the socket can recv/send/accept successfully and on when an error
321  * occurs. The callback may also be called spuriously without reason.
322  *
323  * The callback may be called in an interrupt context and should not
324  * perform expensive operations such as recv/send calls.
325  *
326  * @param handle Socket handle
327  * @param callback Function to call on state change
328  * @param data Argument to pass to callback
329  */
330  virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), void *data);
331 
332  /* Set stack-specific socket options
333  *
334  * The setsockopt allow an application to pass stack-specific hints
335  * to the underlying stack. For unsupported options,
336  * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
337  *
338  * @param handle Socket handle
339  * @param level Stack-specific protocol level
340  * @param optname Stack-specific option identifier
341  * @param optval Option value
342  * @param optlen Length of the option value
343  * @return 0 on success, negative error code on failure
344  */
345  virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
346  int optname, const void *optval, unsigned optlen);
347 
348  /* Get stack-specific socket options
349  *
350  * The getstackopt allow an application to retrieve stack-specific hints
351  * from the underlying stack. For unsupported options,
352  * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
353  *
354  * @param handle Socket handle
355  * @param level Stack-specific protocol level
356  * @param optname Stack-specific option identifier
357  * @param optval Destination for option value
358  * @param optlen Length of the option value
359  * @return 0 on success, negative error code on failure
360  */
361  virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level,
362  int optname, void *optval, unsigned *optlen);
363 
364 private:
365 
366  /** Call in callback
367  *
368  * Callback is used to call the call in method of the network stack.
369  */
371 
372  /** Get a call in callback
373  *
374  * Get a call in callback from the network stack context.
375  *
376  * Callback should not take more than 10ms to execute, otherwise it might
377  * prevent underlying thread processing. A portable user of the callback
378  * should not make calls to network operations due to stack size limitations.
379  * The callback should not perform expensive operations such as socket recv/send
380  * calls or blocking operations.
381  *
382  * @return Call in callback
383  */
384  virtual call_in_callback_cb_t get_call_in_callback();
385 
386  /** Call a callback after a delay
387  *
388  * Call a callback from the network stack context after a delay. If function
389  * returns error callback will not be called.
390  *
391  * @param delay Delay in milliseconds
392  * @param func Callback to be called
393  * @return 0 on success, negative error code on failure
394  */
395  virtual nsapi_error_t call_in(int delay, mbed::Callback<void()> func);
396 
397  Interface *m_interface;
398 };
399 
400 #endif /* EMAC_TEST_NETWORK_STACK_H */
virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address)
Bind a specific address to a socket.
virtual nsapi_error_t bringdown()
Disconnect interface from the network.
Representation of a stack&#39;s view of an interface.
void * nsapi_socket_t
Opaque handle for network sockets.
Definition: nsapi_types.h:252
virtual nsapi_error_t get_netmask(SocketAddress *address)
Copies netmask of the network interface to user supplied buffer.
signed int nsapi_error_t
Type used to represent error codes.
Definition: nsapi_types.h:140
virtual nsapi_size_or_error_t socket_recv(nsapi_socket_t handle, void *data, nsapi_size_t size)
Receive data over a TCP socket.
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:151
virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level, int optname, void *optval, unsigned *optlen)
Get stack-specific socket options.
virtual void socket_attach(nsapi_socket_t handle, void(*callback)(void *), void *data)
Register a callback on state change of the socket.
virtual nsapi_error_t add_dns_server(const SocketAddress &address)
Add a domain name server to list of servers to query.
mbed OS API for onboard IP stack abstraction
virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address)
Connects TCP socket to a remote host.
virtual nsapi_size_or_error_t socket_send(nsapi_socket_t handle, const void *data, nsapi_size_t size)
Send data over a TCP socket.
virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto)
Opens a socket.
SocketAddress class.
Definition: SocketAddress.h:37
virtual nsapi_error_t get_gateway(SocketAddress *address)
Copies gateway address of the network interface to user supplied buffer.
virtual nsapi_error_t socket_accept(nsapi_socket_t server, nsapi_socket_t *handle, SocketAddress *address=0)
Accepts a connection on a TCP socket.
virtual void attach(mbed::Callback< void(nsapi_event_t, intptr_t)> status_cb)
Register callback for status reporting.
virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level, int optname, const void *optval, unsigned optlen)
Set stack-specific socket options.
virtual nsapi_error_t add_ethernet_interface(EMAC &emac, bool default_if, OnboardNetworkStack::Interface **interface_out)
Register a network interface with the IP stack.
virtual nsapi_size_or_error_t socket_sendto(nsapi_socket_t handle, const SocketAddress &address, const void *data, nsapi_size_t size)
Send a packet over a UDP socket.
virtual nsapi_error_t bringup(bool dhcp, const char *ip, const char *netmask, const char *gw, nsapi_ip_stack_t stack=DEFAULT_STACK, bool blocking=true)
Connect the interface to the network.
virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog)
Listen for connections on a TCP socket.
virtual nsapi_size_or_error_t socket_recvfrom(nsapi_socket_t handle, SocketAddress *address, void *buffer, nsapi_size_t size)
Receive a packet over a UDP socket.
unsigned int nsapi_size_t
Type used to represent the size of data passed through sockets.
Definition: nsapi_types.h:144
This interface should be used to abstract low level access to networking hardware All operations rece...
Definition: EMAC.h:33
virtual char * get_mac_address(char *buf, nsapi_size_t buflen)
Return MAC address of the network interface.
virtual nsapi_connection_status_t get_connection_status() const
Get the connection status.
virtual nsapi_error_t get_ip_address(SocketAddress *address)
Copies IP address of the network interface to user supplied buffer.
virtual nsapi_error_t socket_close(nsapi_socket_t handle)
Close the socket.
Callback class based on template specialization.
Definition: Callback.h:53
virtual nsapi_error_t gethostbyname(const char *host, SocketAddress *address, nsapi_version_t version=NSAPI_UNSPEC)
Translates a hostname to an IP address with specific version.
#define MBED_DEPRECATED_SINCE(D, M)
MBED_DEPRECATED("message string") Mark a function declaration as deprecated, if it used then a warnin...
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.