mbed-os/features/netsocket/OnboardNetworkStack.h

/* mbed OS IP stack API
 * Copyright (c) 2015-2017 ARM Limited
 *
 * 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"

/**
 * 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 {
    public:
        virtual ~Interface() {}

        /** 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;

        /** 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;

        /** Copies IP address of the network interface to user supplied buffer
         *
         * @param    buf        buffer to which IP address will be copied as "W:X:Y:Z"
         * @param    buflen     size of supplied buffer
         * @return              Pointer to a buffer, or NULL if the buffer is too small
         */
        virtual char *get_ip_address(char *buf, nsapi_size_t buflen) = 0;

        /** Copies netmask of the network interface to user supplied buffer
         *
         * @param    buf        buffer to which netmask will be copied as "W:X:Y:Z"
         * @param    buflen     size of supplied buffer
         * @return              Pointer to a buffer, or NULL if the buffer is too small
         */
        virtual char *get_netmask(char *buf, nsapi_size_t buflen) = 0;

        /** Copies gateway address of the network interface to user supplied buffer
         *
         * @param    buf        buffer to which gateway address will be copied as "W:X:Y:Z"
         * @param    buflen     size of supplied buffer
         * @return              Pointer to a buffer, or NULL if the buffer is too small
         */
        virtual char *get_gateway(char *buf, nsapi_size_t buflen) = 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    pointer to stack interface object controlling the EMAC
     * @return                      NSAPI_ERROR_OK on success, or error code
     */
    virtual nsapi_error_t add_ethernet_interface(EMAC &emac, bool default_if, Interface **interface_out) = 0;
};

#endif /* MBED_IPSTACK_H */