OnboardNetworkStack.h

00001 /* mbed OS IP stack API
00002  * Copyright (c) 2015-2017 ARM Limited
00003  *
00004  * Licensed under the Apache License, Version 2.0 (the "License");
00005  * you may not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  *     http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an "AS IS" BASIS,
00012  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 #ifndef MBED_IPSTACK_H
00018 #define MBED_IPSTACK_H
00019 
00020 #include "nsapi.h"
00021 
00022 #include "NetworkStack.h"
00023 #include "EMAC.h"
00024 #include "L3IP.h"
00025 #include "PPP.h"
00026 
00027 /**
00028  * mbed OS API for onboard IP stack abstraction
00029  *
00030  * This interface should be used by targets to initialize IP stack, create, bring up and bring down network interfaces.
00031  *
00032  * An onboard network stack has the potential ability to register interfaces
00033  * such as through EMAC, and has its own interface identifiers.
00034  */
00035 class OnboardNetworkStack : public NetworkStack {
00036 public:
00037     /** Return the default on-board network stack
00038      *
00039      * Returns the default on-board network stack, as configured by
00040      * JSON option nsapi.default-stack.
00041      */
00042     static OnboardNetworkStack &get_default_instance();
00043 
00044     /** Representation of a stack's view of an interface.
00045      *
00046      * Provides facilities required by a driver to implement the application
00047      * NetworkInterface API.
00048      */
00049     class Interface {
00050     public:
00051         virtual ~Interface() {}
00052 
00053         /** Connect the interface to the network
00054          *
00055          * Sets up a connection on specified network interface, using DHCP or provided network details. If the @a dhcp is set to
00056          * true all the remaining parameters are ignored.
00057          *
00058          * @param    dhcp       true if the network details should be acquired using DHCP
00059          * @param    ip         IP address to be used for the interface as "W:X:Y:Z" or NULL
00060          * @param    netmask    Net mask to be used for the interface as "W:X:Y:Z" or NULL
00061          * @param    gw         Gateway address to be used for the interface as "W:X:Y:Z" or NULL
00062          * @param    stack      Allow manual selection of IPv4 and/or IPv6.
00063          * @param    blocking   Specify whether bringup blocks for connection completion.
00064          * @return              NSAPI_ERROR_OK on success, or error code
00065          */
00066         virtual nsapi_error_t bringup(bool dhcp, const char *ip,
00067                                       const char *netmask, const char *gw,
00068                                       nsapi_ip_stack_t stack = DEFAULT_STACK,
00069                                       bool blocking = true) = 0;
00070 
00071         /** Disconnect interface from the network
00072          *
00073          * After this call the network interface is inactive, to use it again user needs to call @n bringup again.
00074          *
00075          * @return    NSAPI_ERROR_OK on success, or error code
00076          */
00077         virtual nsapi_error_t bringdown() = 0;
00078 
00079         /** Register callback for status reporting
00080          *
00081          *  The specified status callback function will be called on status changes
00082          *  on the network. The parameters on the callback are the event type and
00083          *  event-type dependent reason parameter.
00084          *
00085          *  @param status_cb The callback for status changes
00086          */
00087         virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
00088 
00089         /** Get the connection status
00090          *
00091          *  @return         The connection status according to ConnectionStatusType
00092          */
00093 
00094         virtual nsapi_connection_status_t get_connection_status() const = 0;
00095 
00096         /** Returns interface name
00097         *
00098         * @return  string containing name of network interface for example "en0"
00099         */
00100 
00101         virtual char *get_interface_name(char *buf)
00102         {
00103             return NULL;
00104         };
00105         /** Return MAC address of the network interface
00106          *
00107          * @return              MAC address as "V:W:X:Y:Z"
00108          */
00109 
00110         virtual char *get_mac_address(char *buf, nsapi_size_t buflen) = 0;
00111 
00112         /** @copydoc NetworkStack::get_ip_address */
00113         virtual nsapi_error_t get_ip_address (SocketAddress *address) = 0;
00114 
00115         MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
00116         virtual char *get_ip_address (char *buf, nsapi_size_t buflen) = 0;
00117 
00118         /** @copydoc NetworkStack::get_ipv6_link_local_address */
00119         virtual nsapi_error_t get_ipv6_link_local_address (SocketAddress *address)
00120         {
00121             return NSAPI_ERROR_UNSUPPORTED ;
00122         }
00123 
00124         /** @copydoc NetworkStack::get_netmask */
00125         virtual nsapi_error_t get_netmask (SocketAddress *address) = 0;
00126 
00127         MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
00128         virtual char *get_netmask (char *buf, nsapi_size_t buflen) = 0;
00129 
00130         /** @copydoc NetworkStack::get_gateway */
00131         virtual nsapi_error_t get_gateway (SocketAddress *address) = 0;
00132 
00133         MBED_DEPRECATED_SINCE("mbed-os-5.15", "String-based APIs are deprecated")
00134         virtual char *get_gateway (char *buf, nsapi_size_t buflen) = 0;
00135     };
00136 
00137     /** Register a network interface with the IP stack
00138      *
00139      * Connects EMAC layer with the IP stack and initializes all the required infrastructure.
00140      * This function should be called only once for each available interface. EMAC memory
00141      * manager is available to EMAC after this function call.
00142      *
00143      * @param      emac             EMAC HAL implementation for this network interface
00144      * @param      default_if       true if the interface should be treated as the default one
00145      * @param[out] interface_out    pointer to stack interface object controlling the EMAC
00146      * @return                      NSAPI_ERROR_OK on success, or error code
00147      */
00148     virtual nsapi_error_t add_ethernet_interface(EMAC &emac, bool default_if, Interface **interface_out) = 0;
00149 
00150     virtual nsapi_error_t add_l3ip_interface(L3IP &l3ip, bool default_if, Interface **interface_out)
00151     {
00152         return NSAPI_ERROR_OK ;
00153     };
00154 
00155     virtual nsapi_error_t add_ppp_interface(PPP &ppp, bool default_if, Interface **interface_out)
00156     {
00157         return NSAPI_ERROR_UNSUPPORTED ;
00158     };
00159 
00160     virtual nsapi_error_t remove_l3ip_interface(Interface **interface_out)
00161     {
00162         return NSAPI_ERROR_OK ;
00163     };
00164 
00165     virtual nsapi_error_t remove_ppp_interface(Interface **interface_out)
00166     {
00167         return NSAPI_ERROR_UNSUPPORTED ;
00168     };
00169 
00170     virtual void set_default_interface(OnboardNetworkStack::Interface *interface)
00171     {
00172     }
00173 
00174 };
00175 
00176 #endif /* MBED_IPSTACK_H */