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