Mistake on this page?
Report an issue in GitHub or email us
OnboardNetworkStack.h
1 /* mbed OS IP stack API
2  * Copyright (c) 2015-2017 ARM Limited
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef MBED_IPSTACK_H
18 #define MBED_IPSTACK_H
19 
20 #include "nsapi.h"
21 
22 #include "NetworkStack.h"
23 #include "EMAC.h"
24 #include "L3IP.h"
25 #include "PPP.h"
26 
27 /**
28  * mbed OS API for onboard IP stack abstraction
29  *
30  * This interface should be used by targets to initialize IP stack, create, bring up and bring down network interfaces.
31  *
32  * An onboard network stack has the potential ability to register interfaces
33  * such as through EMAC, and has its own interface identifiers.
34  */
36 public:
37  /** Return the default on-board network stack
38  *
39  * Returns the default on-board network stack, as configured by
40  * JSON option nsapi.default-stack.
41  */
43 
44  /** Representation of a stack's view of an interface.
45  *
46  * Provides facilities required by a driver to implement the application
47  * NetworkInterface API.
48  */
49  class Interface {
50  protected:
51  ~Interface() = default;
52 
53  public:
54  /** Set IP address
55  *
56  * bringup() can only take one IP address and in dual stack case
57  * another IP address can be set using this function.
58  *
59  * Must be called before bringup().
60  *
61  * @param ip IP address to be used for the interface as "W:X:Y:Z" or NULL
62  * @param netmask Net mask to be used for the interface as "W:X:Y:Z" or NULL
63  * @param gw Gateway address to be used for the interface as "W:X:Y:Z" or NULL
64  * @param ipv6_flag Provide this flag for IPv6 state flag override. For example, you can set IP6_ADDR_PREFERRED.
65  * For IPv4, this value will be ignored.
66  * @return NSAPI_ERROR_OK on success, or error code
67  */
68  virtual nsapi_error_t set_ip_address(const char *ip,
69  const char *netmask,
70  const char *gw,
71  uint8_t ipv6_flag)
72  {
74  }
75 
76  /** Connect the interface to the network
77  *
78  * Sets up a connection on specified network interface, using DHCP or provided network details. If the @a dhcp is set to
79  * true all the remaining parameters are ignored.
80  *
81  * @param dhcp true if the network details should be acquired using DHCP
82  * @param ip IP address to be used for the interface as "W:X:Y:Z" or NULL
83  * @param netmask Net mask to be used for the interface as "W:X:Y:Z" or NULL
84  * @param gw Gateway address to be used for the interface as "W:X:Y:Z" or NULL
85  * @param stack Allow manual selection of IPv4 and/or IPv6.
86  * @param blocking Specify whether bringup blocks for connection completion.
87  * @return NSAPI_ERROR_OK on success, or error code
88  */
89  virtual nsapi_error_t bringup(bool dhcp, const char *ip,
90  const char *netmask, const char *gw,
91  nsapi_ip_stack_t stack = DEFAULT_STACK,
92  bool blocking = true) = 0;
93 
94  /** Disconnect interface from the network
95  *
96  * After this call the network interface is inactive, to use it again user needs to call @n bringup again.
97  *
98  * @return NSAPI_ERROR_OK on success, or error code
99  */
100  virtual nsapi_error_t bringdown() = 0;
101 
102  /** Register callback for status reporting
103  *
104  * The specified status callback function will be called on status changes
105  * on the network. The parameters on the callback are the event type and
106  * event-type dependent reason parameter.
107  *
108  * @param status_cb The callback for status changes
109  */
110  virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
111 
112  /** Get the connection status
113  *
114  * @return The connection status according to ConnectionStatusType
115  */
116 
117  virtual nsapi_connection_status_t get_connection_status() const = 0;
118 
119  /** Returns interface name
120  *
121  * @return string containing name of network interface for example "en0"
122  */
123 
124  virtual char *get_interface_name(char *buf)
125  {
126  return NULL;
127  };
128  /** Return MAC address of the network interface
129  *
130  * @return MAC address as "V:W:X:Y:Z"
131  */
132 
133  virtual char *get_mac_address(char *buf, nsapi_size_t buflen) = 0;
134 
135  /** @copydoc NetworkStack::get_ip_address */
136  virtual nsapi_error_t get_ip_address(SocketAddress *address) = 0;
137 
138  /** @copydoc NetworkStack::get_ipv6_link_local_address */
140  {
142  }
143 
144  /** @copydoc NetworkStack::get_netmask */
145  virtual nsapi_error_t get_netmask(SocketAddress *address) = 0;
146 
147  /** @copydoc NetworkStack::get_gateway */
148  virtual nsapi_error_t get_gateway(SocketAddress *address) = 0;
149  };
150 
151  /** Register a network interface with the IP stack
152  *
153  * Connects EMAC layer with the IP stack and initializes all the required infrastructure.
154  * This function should be called only once for each available interface. EMAC memory
155  * manager is available to EMAC after this function call.
156  *
157  * @param emac EMAC HAL implementation for this network interface
158  * @param default_if true if the interface should be treated as the default one
159  * @param[out] interface_out pointer to stack interface object controlling the EMAC
160  * @return NSAPI_ERROR_OK on success, or error code
161  */
162  virtual nsapi_error_t add_ethernet_interface(EMAC &emac, bool default_if, Interface **interface_out) = 0;
163 
164  virtual nsapi_error_t add_l3ip_interface(L3IP &l3ip, bool default_if, Interface **interface_out)
165  {
166  return NSAPI_ERROR_OK;
167  };
168 
169  virtual nsapi_error_t add_ppp_interface(PPP &ppp, bool default_if, Interface **interface_out)
170  {
172  };
173 
174  virtual nsapi_error_t remove_ethernet_interface(Interface **interface_out)
175  {
176  return NSAPI_ERROR_OK;
177  };
178 
179  virtual nsapi_error_t remove_l3ip_interface(Interface **interface_out)
180  {
181  return NSAPI_ERROR_OK;
182  };
183 
184  virtual nsapi_error_t remove_ppp_interface(Interface **interface_out)
185  {
187  };
188 
189  virtual void set_default_interface(OnboardNetworkStack::Interface *interface)
190  {
191  }
192 
194  {
195  return this;
196  }
197 };
198 
199 #endif /* MBED_IPSTACK_H */
virtual char * get_interface_name(char *buf)
Returns interface name.
NetworkStack class.
Definition: NetworkStack.h:41
virtual nsapi_error_t get_netmask(SocketAddress *address)=0
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:95
OnboardNetworkStack * onboardNetworkStack() final
Dynamic downcast to a OnboardNetworkStack.
virtual nsapi_error_t get_gateway(SocketAddress *address)=0
virtual void attach(mbed::Callback< void(nsapi_event_t, intptr_t)> status_cb)=0
Register callback for status reporting.
virtual nsapi_error_t set_ip_address(const char *ip, const char *netmask, const char *gw, uint8_t ipv6_flag)
Set IP address.
mbed OS API for onboard IP stack abstraction
virtual nsapi_error_t add_ethernet_interface(EMAC &emac, bool default_if, Interface **interface_out)=0
Register a network interface with the IP stack.
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)=0
Connect the interface to the network.
Definition: PPP.h:26
This interface should be used to abstract low level access to networking hardware All operations rece...
Definition: L3IP.h:31
SocketAddress class.
Definition: SocketAddress.h:36
virtual nsapi_error_t bringdown()=0
Disconnect interface from the network.
virtual nsapi_error_t get_ip_address(SocketAddress *address)=0
Get the local IP address.
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
NetworkStack class.
virtual nsapi_error_t get_ipv6_link_local_address(SocketAddress *address)
Get the IPv6 link local address.
virtual char * get_mac_address(char *buf, nsapi_size_t buflen)=0
Return MAC address of the network interface.
static OnboardNetworkStack & get_default_instance()
Return the default on-board network stack.
virtual nsapi_connection_status_t get_connection_status() const =0
Get the connection status.
Callback class based on template specialization.
Definition: Callback.h:53
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.