/* mbed OS IP stack API
* Copyright (c) 2015-2017 ARM Limited
* SPDX-License-Identifier: Apache-2.0
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
#ifndef MBED_IPSTACK_H
#define MBED_IPSTACK_H
#include "nsapi.h"
#include "NetworkStack.h"
#include "EMAC.h"
#include "L3IP.h"
#include "PPP.h"
/**
* mbed OS API for onboard IP stack abstraction
*
* This interface should be used by targets to initialize IP stack, create, bring up and bring down network interfaces.
*
* An onboard network stack has the potential ability to register interfaces
* such as through EMAC, and has its own interface identifiers.
*/
class OnboardNetworkStack : public NetworkStack {
public:
/** Return the default on-board network stack
*
* Returns the default on-board network stack, as configured by
* JSON option nsapi.default-stack.
*/
static OnboardNetworkStack &get_default_instance();
/** Representation of a stack's view of an interface.
*
* Provides facilities required by a driver to implement the application
* NetworkInterface API.
*/
class Interface {
protected:
~Interface() = default;
public:
/** Set IP address
*
* bringup() can only take one IP address and in dual stack case
* another IP address can be set using this function.
*
* Must be called before bringup().
*
* @param ip IP address to be used for the interface as "W:X:Y:Z" or NULL
* @param netmask Net mask to be used for the interface as "W:X:Y:Z" or NULL
* @param gw Gateway address to be used for the interface as "W:X:Y:Z" or NULL
* @param ipv6_flag Provide this flag for IPv6 state flag override. For example, you can set IP6_ADDR_PREFERRED.
* For IPv4, this value will be ignored.
* @return NSAPI_ERROR_OK on success, or error code
*/
virtual nsapi_error_t set_ip_address(const char *ip,
const char *netmask,
const char *gw,
uint8_t ipv6_flag)
{
return NSAPI_ERROR_UNSUPPORTED;
}
/** Connect the interface to the network
*
* Sets up a connection on specified network interface, using DHCP or provided network details. If the @a dhcp is set to
* true all the remaining parameters are ignored.
*
* @param dhcp true if the network details should be acquired using DHCP
* @param ip IP address to be used for the interface as "W:X:Y:Z" or NULL
* @param netmask Net mask to be used for the interface as "W:X:Y:Z" or NULL
* @param gw Gateway address to be used for the interface as "W:X:Y:Z" or NULL
* @param stack Allow manual selection of IPv4 and/or IPv6.
* @param blocking Specify whether bringup blocks for connection completion.
* @return NSAPI_ERROR_OK on success, or error code
*/
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;
/** Disconnect interface from the network
*
* After this call the network interface is inactive, to use it again user needs to call @n bringup again.
*
* @return NSAPI_ERROR_OK on success, or error code
*/
virtual nsapi_error_t bringdown() = 0;
/** Register callback for status reporting
*
* The specified status callback function will be called on status changes
* on the network. The parameters on the callback are the event type and
* event-type dependent reason parameter.
*
* @param status_cb The callback for status changes
*/
virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
/** Get the connection status
*
* @return The connection status according to ConnectionStatusType
*/
virtual nsapi_connection_status_t get_connection_status() const = 0;
/** Returns interface name
*
* @return string containing name of network interface for example "en0"
*/
virtual char *get_interface_name(char *buf)
{
return NULL;
};
/** Return MAC address of the network interface
*
* @return MAC address as "V:W:X:Y:Z"
*/
virtual char *get_mac_address(char *buf, nsapi_size_t buflen) = 0;
/** @copydoc NetworkStack::get_ip_address */
virtual nsapi_error_t get_ip_address(SocketAddress *address) = 0;
/** @copydoc NetworkStack::get_ipv6_link_local_address */
virtual nsapi_error_t get_ipv6_link_local_address(SocketAddress *address)
{
return NSAPI_ERROR_UNSUPPORTED;
}
/** Writes the netmask of the network interface into a user-supplied #SocketAddress.
*
* @param address Structure to write netmask into.
* @return Error code or success.
*/
virtual nsapi_error_t get_netmask(SocketAddress *address) = 0;
/** Writes the gateway address of the network interface into a user-supplied #SocketAddress.
*
* @param address Structure to write netmask into.
* @return Error code or success.
*/
virtual nsapi_error_t get_gateway(SocketAddress *address) = 0;
};
/** Register a network interface with the IP stack
*
* Connects EMAC layer with the IP stack and initializes all the required infrastructure.
* This function should be called only once for each available interface. EMAC memory
* manager is available to EMAC after this function call.
*
* @param emac EMAC HAL implementation for this network interface
* @param default_if true if the interface should be treated as the default one
* @param[out] interface_out Network stack's representation of the network interface will be saved to this pointer.
* @param[in] user_network_interface Pointer to NetworkInterface that represents the ethernet interface being added.
* @return NSAPI_ERROR_OK on success, or error code
*/
virtual nsapi_error_t add_ethernet_interface(EMAC &emac, bool default_if, Interface **interface_out, NetworkInterface *user_network_interface = NULL) = 0;
virtual nsapi_error_t add_ethernet_interface(EMAC &emac, bool default_if, Interface **interface_out, const uint8_t *mac_addr, NetworkInterface *user_network_interface = NULL)
{
return NSAPI_ERROR_UNSUPPORTED;
}
virtual nsapi_error_t add_l3ip_interface(L3IP &l3ip, bool default_if, Interface **interface_out)
{
return NSAPI_ERROR_OK;
};
virtual nsapi_error_t add_ppp_interface(PPP &ppp, bool default_if, Interface **interface_out)
{
return NSAPI_ERROR_UNSUPPORTED;
};
virtual nsapi_error_t remove_ethernet_interface(Interface **interface_out)
{
return NSAPI_ERROR_OK;
};
virtual nsapi_error_t remove_l3ip_interface(Interface **interface_out)
{
return NSAPI_ERROR_OK;
};
virtual nsapi_error_t remove_ppp_interface(Interface **interface_out)
{
return NSAPI_ERROR_UNSUPPORTED;
};
virtual void set_default_interface(OnboardNetworkStack::Interface *interface)
{
}
OnboardNetworkStack *onboardNetworkStack() final
{
return this;
}
};
#endif /* MBED_IPSTACK_H */
