L3IPInterface.h

00001 /*
00002  * Copyright (c) 2018 ARM Limited
00003  * SPDX-License-Identifier: Apache-2.0
00004  *
00005  * Licensed under the Apache License, Version 2.0 (the "License");
00006  * you may not use this file except in compliance with the License.
00007  * You may obtain a copy of the License at
00008  *
00009  *     http://www.apache.org/licenses/LICENSE-2.0
00010  *
00011  * Unless required by applicable law or agreed to in writing, software
00012  * distributed under the License is distributed on an "AS IS" BASIS,
00013  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00014  * See the License for the specific language governing permissions and
00015  * limitations under the License.
00016  */
00017 
00018 #ifndef L3IP_INTERFACE_H
00019 #define L3IP_INTERFACE_H
00020 
00021 #include "nsapi.h"
00022 #include "L3IP.h"
00023 #include "OnboardNetworkStack.h"
00024 
00025 
00026 /** L3IPInterface class
00027  *  Implementation of the NetworkInterface for an IP-based driver
00028  *
00029  * This class provides the necessary glue logic to create a NetworkInterface
00030  * based on an L3IP and an OnboardNetworkStack. Cellular Interface  drivers derive from it.
00031  *
00032  * Drivers derived from L3IPInterface should be constructed so that their
00033  * L3IP is functional without the need to call `connect()`.
00034  */
00035 class L3IPInterface : public virtual NetworkInterface {
00036 public:
00037     /** Create an L3IP-based network interface.
00038      *
00039      * The default arguments obtain the default L3IP, which will be target-
00040      * dependent (and the target may have some JSON option to choose which
00041      * is the default, if there are multiple). The default stack is configured
00042      * by JSON option nsapi.default-stack.
00043      *
00044      * Due to inability to return errors from the constructor, no real
00045      * work is done until the first call to connect().
00046      *
00047      * @param l3ip  Reference to L3IP to use
00048      * @param stack Reference to onboard-network stack to use
00049      */
00050     L3IPInterface(L3IP &l3ip = L3IP::get_default_instance(),
00051                   OnboardNetworkStack &stack = OnboardNetworkStack::get_default_instance());
00052     virtual ~L3IPInterface();
00053     /** Set a static IP address
00054      *
00055      *  Configures this network interface to use a static IP address.
00056      *  Implicitly disables DHCP, which can be enabled in set_dhcp.
00057      *  Requires that the network is disconnected.
00058      *
00059      *  @param ip_address  Null-terminated representation of the local IP address
00060      *  @param netmask     Null-terminated representation of the local network mask
00061      *  @param gateway     Null-terminated representation of the local gateway
00062      *  @return            0 on success, negative error code on failure
00063      */
00064     virtual nsapi_error_t set_network(const char *ip_address, const char *netmask, const char *gateway);
00065 
00066     /** Enable or disable DHCP on the network
00067      *
00068      *  Requires that the network is disconnected
00069      *
00070      *  @param dhcp     False to disable dhcp (defaults to enabled)
00071      *  @return         0 on success, negative error code on failure
00072      */
00073     virtual nsapi_error_t set_dhcp(bool dhcp);
00074 
00075     /** Start the interface
00076      *  @return             0 on success, negative on failure
00077      */
00078     virtual nsapi_error_t connect();
00079 
00080     /** Stop the interface
00081      *  @return             0 on success, negative on failure
00082      */
00083     virtual nsapi_error_t disconnect();
00084 
00085     /** Get the local IP address
00086      *
00087      *  @return         Null-terminated representation of the local IP address
00088      *                  or null if no IP address has been received
00089      */
00090     virtual const char *get_ip_address();
00091 
00092     /** Get the local network mask
00093      *
00094      *  @return         Null-terminated representation of the local network mask
00095      *                  or null if no network mask has been received
00096      */
00097     virtual const char *get_netmask();
00098 
00099     /** Get the local gateways
00100      *
00101      *  @return         Null-terminated representation of the local gateway
00102      *                  or null if no network mask has been received
00103      */
00104     virtual const char *get_gateway();
00105 
00106     /** Get the network interface name
00107      *
00108      *  @return         Null-terminated representation of the network interface name
00109      *                  or null if  interface not exists
00110      */
00111     virtual char *get_interface_name(char *interface_name);
00112 
00113     /** Set the network interface as default one
00114       */
00115     virtual void set_as_default();
00116 
00117     /** Register callback for status reporting
00118      *
00119      *  @param status_cb The callback for status changes
00120      */
00121     virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
00122 
00123     /** Get the connection status
00124      *
00125      *  @return         The connection status according to nsapi_connection_status_t
00126      */
00127     virtual nsapi_connection_status_t get_connection_status() const;
00128 
00129     /** Set blocking status of connect() which by default should be blocking
00130      *
00131      *  @param blocking true if connect is blocking
00132      *  @return         0 on success, negative error code on failure
00133      */
00134     virtual nsapi_error_t set_blocking(bool blocking);
00135 
00136     /** Provide access to the L3IP
00137      *
00138      * This should be used with care - normally the network stack would
00139      * control the L3IP, so manipulating the L3IP while the stack
00140      * is also using it (ie after connect) will likely cause problems.
00141      *
00142      * @return          Reference to the L3IP in use
00143      */
00144     L3IP &getl3ip() const
00145     {
00146         return _l3ip;
00147     }
00148 
00149     virtual L3IPInterface *l3ipInterface()
00150     {
00151         return this;
00152     }
00153 
00154 protected:
00155     /** Provide access to the underlying stack
00156      *
00157      *  @return The underlying network stack
00158      */
00159     virtual NetworkStack *get_stack();
00160 
00161     L3IP &_l3ip;
00162     OnboardNetworkStack &_stack;
00163     OnboardNetworkStack::Interface *_interface;
00164     bool _dhcp;
00165     bool _blocking;
00166     char _ip_address[NSAPI_IPv6_SIZE];
00167     char _netmask[NSAPI_IPv4_SIZE];
00168     char _gateway[NSAPI_IPv4_SIZE];
00169     mbed::Callback<void(nsapi_event_t, intptr_t)> _connection_status_cb;
00170 };
00171 
00172 #endif