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