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 
00025 /**
00026  * mbed OS API for onboard IP stack abstraction
00027  *
00028  * This interface should be used by targets to initialize IP stack, create, bring up and bring down network interfaces.
00029  *
00030  * An onboard network stack has the potential ability to register interfaces
00031  * such as through EMAC, and has its own interface identifiers.
00032  */
00033 class OnboardNetworkStack : public NetworkStack {
00034 public:
00035     /** Return the default on-board network stack
00036      *
00037      * Returns the default on-board network stack, as configured by
00038      * JSON option nsapi.default-stack.
00039      */
00040     static OnboardNetworkStack &get_default_instance();
00041 
00042     /** Representation of a stack's view of an interface.
00043      *
00044      * Provides facilities required by a driver to implement the application
00045      * NetworkInterface API.
00046      */
00047     class Interface {
00048     public:
00049         virtual ~Interface() {}
00050 
00051         /** Connect the interface to the network
00052          *
00053          * Sets up a connection on specified network interface, using DHCP or provided network details. If the @a dhcp is set to
00054          * true all the remaining parameters are ignored.
00055          *
00056          * @param    dhcp       true if the network details should be acquired using DHCP
00057          * @param    ip         IP address to be used for the interface as "W:X:Y:Z" or NULL
00058          * @param    netmask    Net mask to be used for the interface as "W:X:Y:Z" or NULL
00059          * @param    gw         Gateway address to be used for the interface as "W:X:Y:Z" or NULL
00060          * @param    stack      Allow manual selection of IPv4 and/or IPv6.
00061          * @param    blocking   Specify whether bringup blocks for connection completion.
00062          * @return              NSAPI_ERROR_OK on success, or error code
00063          */
00064         virtual nsapi_error_t bringup(bool dhcp, const char *ip,
00065                                       const char *netmask, const char *gw,
00066                                       nsapi_ip_stack_t stack = DEFAULT_STACK,
00067                                       bool blocking = true) = 0;
00068 
00069         /** Disconnect interface from the network
00070          *
00071          * After this call the network interface is inactive, to use it again user needs to call @n bringup again.
00072          *
00073          * @return    NSAPI_ERROR_OK on success, or error code
00074          */
00075         virtual nsapi_error_t bringdown() = 0;
00076 
00077         /** Register callback for status reporting
00078          *
00079          *  The specified status callback function will be called on status changes
00080          *  on the network. The parameters on the callback are the event type and
00081          *  event-type dependent reason parameter.
00082          *
00083          *  @param status_cb The callback for status changes
00084          */
00085         virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb) = 0;
00086 
00087         /** Get the connection status
00088          *
00089          *  @return         The connection status according to ConnectionStatusType
00090          */
00091         virtual nsapi_connection_status_t get_connection_status() const = 0;
00092 
00093         /** Return MAC address of the network interface
00094          *
00095          * @return              MAC address as "V:W:X:Y:Z"
00096          */
00097         virtual char *get_mac_address(char *buf, nsapi_size_t buflen) = 0;
00098 
00099         /** Copies IP address of the network interface to user supplied buffer
00100          *
00101          * @param    buf        buffer to which IP address will be copied as "W:X:Y:Z"
00102          * @param    buflen     size of supplied buffer
00103          * @return              Pointer to a buffer, or NULL if the buffer is too small
00104          */
00105         virtual char *get_ip_address(char *buf, nsapi_size_t buflen) = 0;
00106 
00107         /** Copies netmask of the network interface to user supplied buffer
00108          *
00109          * @param    buf        buffer to which netmask will be copied as "W:X:Y:Z"
00110          * @param    buflen     size of supplied buffer
00111          * @return              Pointer to a buffer, or NULL if the buffer is too small
00112          */
00113         virtual char *get_netmask(char *buf, nsapi_size_t buflen) = 0;
00114 
00115         /** Copies gateway address of the network interface to user supplied buffer
00116          *
00117          * @param    buf        buffer to which gateway address will be copied as "W:X:Y:Z"
00118          * @param    buflen     size of supplied buffer
00119          * @return              Pointer to a buffer, or NULL if the buffer is too small
00120          */
00121         virtual char *get_gateway(char *buf, nsapi_size_t buflen) = 0;
00122     };
00123 
00124     /** Register a network interface with the IP stack
00125      *
00126      * Connects EMAC layer with the IP stack and initializes all the required infrastructure.
00127      * This function should be called only once for each available interface. EMAC memory
00128      * manager is available to EMAC after this function call.
00129      *
00130      * @param      emac             EMAC HAL implementation for this network interface
00131      * @param      default_if       true if the interface should be treated as the default one
00132      * @param[out] interface_out    pointer to stack interface object controlling the EMAC
00133      * @return                      NSAPI_ERROR_OK on success, or error code
00134      */
00135     virtual nsapi_error_t add_ethernet_interface(EMAC &emac, bool default_if, Interface **interface_out) = 0;
00136 };
00137 
00138 #endif /* MBED_IPSTACK_H */