Diff: mbed-os/features/netsocket/OnboardNetworkStack.h

Revision:

0:8fdf9a60065b

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mbed-os/features/netsocket/OnboardNetworkStack.h	Wed Oct 10 00:33:53 2018 +0000
@@ -0,0 +1,138 @@
+/* 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 */