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  /** Set MAC address on the network interface
90  *
91  * @param mac_addr Buffer containing the MAC address in hexadecimal format.
92  * @param addr_len Length of provided buffer in bytes (6 or 8)
93  * @retval NSAPI_ERROR_OK on success
94  * @retval NSAPI_ERROR_UNSUPPORTED if this feature is not supported
95  * @retval NSAPI_ERROR_PARAMETER if address is not valid
96  * @retval NSAPI_ERROR_BUSY if address can't be set.
97  */
98  virtual nsapi_error_t set_mac_address(uint8_t *mac_addr, nsapi_size_t addr_len);
99 
100  /** Copies IP address of the network interface to user supplied buffer
101  *
102  * @param buf buffer to which IP address 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_ip_address(SocketAddress *address);
107 
108  MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
109  virtual char *get_ip_address(char *buf, nsapi_size_t buflen);
110 
111  /** Copies netmask of the network interface to user supplied buffer
112  *
113  * @param buf buffer to which netmask 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_netmask(SocketAddress *address);
118 
119  MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
120  virtual char *get_netmask(char *buf, nsapi_size_t buflen);
121 
122  /** Copies gateway address of the network interface to user supplied buffer
123  *
124  * @param buf buffer to which gateway address will be copied as "W:X:Y:Z"
125  * @param buflen size of supplied buffer
126  * @return Pointer to a buffer, or NULL if the buffer is too small
127  */
128  virtual nsapi_error_t get_gateway(SocketAddress *address);
129 
130  MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
131  virtual char *get_gateway(char *buf, nsapi_size_t buflen);
132 
133  private:
134  friend EmacTestNetworkStack;
135 
136  Interface();
137 
138  EMAC *m_emac;
139  };
140 
141  /** Register a network interface with the IP stack
142  *
143  * Connects EMAC layer with the IP stack and initializes all the required infrastructure.
144  * This function should be called only once for each available interface.
145  *
146  * @param emac EMAC HAL implementation for this network interface
147  * @param default_if true if the interface should be treated as the default one
148  * @param[out] interface_out pointer to stack interface object controlling the EMAC
149  * @return NSAPI_ERROR_OK on success, or error code
150  */
151  virtual nsapi_error_t add_ethernet_interface(EMAC &emac, bool default_if, OnboardNetworkStack::Interface **interface_out);
152 
153  /** Translates a hostname to an IP address with specific version
154  *
155  * The hostname may be either a domain name or an IP address. If the
156  * hostname is an IP address, no network transactions will be performed.
157  *
158  * If no stack-specific DNS resolution is provided, the hostname
159  * will be resolve using a UDP socket on the stack.
160  *
161  * @param host Hostname to resolve
162  * @param address Destination for the host SocketAddress
163  * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
164  * version is chosen by the stack (defaults to NSAPI_UNSPEC)
165  * @return 0 on success, negative error code on failure
166  */
167  virtual nsapi_error_t gethostbyname(const char *host,
168  SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC);
169 
170  /** Add a domain name server to list of servers to query
171  *
172  * @param address Destination for the host address
173  * @return 0 on success, negative error code on failure
174  */
175  virtual nsapi_error_t add_dns_server(const SocketAddress &address);
176 
177 protected:
178 
179  /** Opens a socket
180  *
181  * Creates a network socket and stores it in the specified handle.
182  * The handle must be passed to following calls on the socket.
183  *
184  * A stack may have a finite number of sockets, in this case
185  * NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
186  *
187  * @param handle Destination for the handle to a newly created socket
188  * @param proto Protocol of socket to open, NSAPI_TCP or NSAPI_UDP
189  * @return 0 on success, negative error code on failure
190  */
191  virtual nsapi_error_t socket_open(nsapi_socket_t *handle, nsapi_protocol_t proto);
192 
193  /** Close the socket
194  *
195  * Closes any open connection and deallocates any memory associated
196  * with the socket.
197  *
198  * @param handle Socket handle
199  * @return 0 on success, negative error code on failure
200  */
201  virtual nsapi_error_t socket_close(nsapi_socket_t handle);
202 
203  /** Bind a specific address to a socket
204  *
205  * Binding a socket specifies the address and port on which to receive
206  * data. If the IP address is zeroed, only the port is bound.
207  *
208  * @param handle Socket handle
209  * @param address Local address to bind
210  * @return 0 on success, negative error code on failure.
211  */
212  virtual nsapi_error_t socket_bind(nsapi_socket_t handle, const SocketAddress &address);
213 
214  /** Listen for connections on a TCP socket
215  *
216  * Marks the socket as a passive socket that can be used to accept
217  * incoming connections.
218  *
219  * @param handle Socket handle
220  * @param backlog Number of pending connections that can be queued
221  * simultaneously
222  * @return 0 on success, negative error code on failure
223  */
224  virtual nsapi_error_t socket_listen(nsapi_socket_t handle, int backlog);
225 
226  /** Connects TCP socket to a remote host
227  *
228  * Initiates a connection to a remote server specified by the
229  * indicated address.
230  *
231  * @param handle Socket handle
232  * @param address The SocketAddress of the remote host
233  * @return 0 on success, negative error code on failure
234  */
235  virtual nsapi_error_t socket_connect(nsapi_socket_t handle, const SocketAddress &address);
236 
237  /** Accepts a connection on a TCP socket
238  *
239  * The server socket must be bound and set to listen for connections.
240  * On a new connection, creates a network socket and stores it in the
241  * specified handle. The handle must be passed to following calls on
242  * the socket.
243  *
244  * A stack may have a finite number of sockets, in this case
245  * NSAPI_ERROR_NO_SOCKET is returned if no socket is available.
246  *
247  * This call is non-blocking. If accept would block,
248  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
249  *
250  * @param server Socket handle to server to accept from
251  * @param handle Destination for a handle to the newly created socket
252  * @param address Destination for the remote address or NULL
253  * @return 0 on success, negative error code on failure
254  */
256  nsapi_socket_t *handle, SocketAddress *address = 0);
257 
258  /** Send data over a TCP socket
259  *
260  * The socket must be connected to a remote host. Returns the number of
261  * bytes sent from the buffer.
262  *
263  * This call is non-blocking. If send would block,
264  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
265  *
266  * @param handle Socket handle
267  * @param data Buffer of data to send to the host
268  * @param size Size of the buffer in bytes
269  * @return Number of sent bytes on success, negative error
270  * code on failure
271  */
273  const void *data, nsapi_size_t size);
274 
275  /** Receive data over a TCP socket
276  *
277  * The socket must be connected to a remote host. Returns the number of
278  * bytes received into the buffer.
279  *
280  * This call is non-blocking. If recv would block,
281  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
282  *
283  * @param handle Socket handle
284  * @param data Destination buffer for data received from the host
285  * @param size Size of the buffer in bytes
286  * @return Number of received bytes on success, negative error
287  * code on failure
288  */
290  void *data, nsapi_size_t size);
291 
292  /** Send a packet over a UDP socket
293  *
294  * Sends data to the specified address. Returns the number of bytes
295  * sent from the buffer.
296  *
297  * This call is non-blocking. If sendto would block,
298  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
299  *
300  * @param handle Socket handle
301  * @param address The SocketAddress of the remote host
302  * @param data Buffer of data to send to the host
303  * @param size Size of the buffer in bytes
304  * @return Number of sent bytes on success, negative error
305  * code on failure
306  */
307  virtual nsapi_size_or_error_t socket_sendto(nsapi_socket_t handle, const SocketAddress &address,
308  const void *data, nsapi_size_t size);
309 
310  /** Receive a packet over a UDP socket
311  *
312  * Receives data and stores the source address in address if address
313  * is not NULL. Returns the number of bytes received into the buffer.
314  *
315  * This call is non-blocking. If recvfrom would block,
316  * NSAPI_ERROR_WOULD_BLOCK is returned immediately.
317  *
318  * @param handle Socket handle
319  * @param address Destination for the source address or NULL
320  * @param buffer Destination buffer for data received from the host
321  * @param size Size of the buffer in bytes
322  * @return Number of received bytes on success, negative error
323  * code on failure
324  */
326  void *buffer, nsapi_size_t size);
327 
328  /** Register a callback on state change of the socket
329  *
330  * The specified callback will be called on state changes such as when
331  * the socket can recv/send/accept successfully and on when an error
332  * occurs. The callback may also be called spuriously without reason.
333  *
334  * The callback may be called in an interrupt context and should not
335  * perform expensive operations such as recv/send calls.
336  *
337  * @param handle Socket handle
338  * @param callback Function to call on state change
339  * @param data Argument to pass to callback
340  */
341  virtual void socket_attach(nsapi_socket_t handle, void (*callback)(void *), void *data);
342 
343  /* Set stack-specific socket options
344  *
345  * The setsockopt allow an application to pass stack-specific hints
346  * to the underlying stack. For unsupported options,
347  * NSAPI_ERROR_UNSUPPORTED is returned and the socket is unmodified.
348  *
349  * @param handle Socket handle
350  * @param level Stack-specific protocol level
351  * @param optname Stack-specific option identifier
352  * @param optval Option value
353  * @param optlen Length of the option value
354  * @return 0 on success, negative error code on failure
355  */
356  virtual nsapi_error_t setsockopt(nsapi_socket_t handle, int level,
357  int optname, const void *optval, unsigned optlen);
358 
359  /* Get stack-specific socket options
360  *
361  * The getstackopt allow an application to retrieve stack-specific hints
362  * from the underlying stack. For unsupported options,
363  * NSAPI_ERROR_UNSUPPORTED is returned and optval is unmodified.
364  *
365  * @param handle Socket handle
366  * @param level Stack-specific protocol level
367  * @param optname Stack-specific option identifier
368  * @param optval Destination for option value
369  * @param optlen Length of the option value
370  * @return 0 on success, negative error code on failure
371  */
372  virtual nsapi_error_t getsockopt(nsapi_socket_t handle, int level,
373  int optname, void *optval, unsigned *optlen);
374 
375 private:
376 
377  /** Call in callback
378  *
379  * Callback is used to call the call in method of the network stack.
380  */
382 
383  /** Get a call in callback
384  *
385  * Get a call in callback from the network stack context.
386  *
387  * Callback should not take more than 10ms to execute, otherwise it might
388  * prevent underlying thread processing. A portable user of the callback
389  * should not make calls to network operations due to stack size limitations.
390  * The callback should not perform expensive operations such as socket recv/send
391  * calls or blocking operations.
392  *
393  * @return Call in callback
394  */
395  virtual call_in_callback_cb_t get_call_in_callback();
396 
397  /** Call a callback after a delay
398  *
399  * Call a callback from the network stack context after a delay. If function
400  * returns error callback will not be called.
401  *
402  * @param delay Delay in milliseconds
403  * @param func Callback to be called
404  * @return 0 on success, negative error code on failure
405  */
406  virtual nsapi_error_t call_in(int delay, mbed::Callback<void()> func);
407 
408  Interface *m_interface;
409 };
410 
411 #endif /* EMAC_TEST_NETWORK_STACK_H */
virtual nsapi_error_t set_mac_address(uint8_t *mac_addr, nsapi_size_t addr_len)
Set MAC address on the network interface.
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.