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