NetworkInterface.h

00001 /* NetworkStack
00002  * Copyright (c) 2015 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 NETWORK_INTERFACE_H
00018 #define NETWORK_INTERFACE_H
00019 
00020 #include "netsocket/nsapi_types.h"
00021 #include "netsocket/SocketAddress.h"
00022 #include "Callback.h"
00023 #include "DNS.h"
00024 
00025 
00026 // Predeclared classes
00027 class NetworkStack;
00028 class EthInterface;
00029 class WiFiInterface;
00030 class MeshInterface;
00031 class CellularBase;
00032 class EMACInterface;
00033 
00034 /** NetworkInterface class
00035  *
00036  *  Common interface that is shared between network devices
00037  *  @addtogroup netsocket
00038  */
00039 class NetworkInterface: public DNS {
00040 public:
00041 
00042     virtual ~NetworkInterface() {};
00043 
00044     /** Return the default network interface
00045      *
00046      * Returns the default network interface, as determined by JSON option
00047      * target.network-default-interface-type or other overrides.
00048      *
00049      * The type of the interface returned can be tested via the ethInterface()
00050      * etc downcasts.
00051      *
00052      * The default behaviour is to return the default interface for the
00053      * interface type specified by target.network-default-interface-type. Targets
00054      * should set this in their targets.json to guide default selection,
00055      * and applications may override.
00056      *
00057      * The interface returned should be already configured for use such that its
00058      * connect() method works with no parameters. For connection types needing
00059      * configuration, settings should normally be obtained from JSON - the
00060      * settings for the core types are under the "nsapi" JSON config tree.
00061      *
00062      * The list of possible settings for default interface type is open-ended,
00063      * as is the number of possible providers. Core providers are:
00064      *
00065      * * ETHERNET: EthernetInterface, using default EMAC and OnboardNetworkStack
00066      * * MESH: ThreadInterface or LoWPANNDInterface, using default NanostackRfPhy
00067      * * CELLULAR: OnboardModemInterface
00068      * * WIFI: None - always provided by a specific class
00069      *
00070      * Specific drivers may be activated by other settings of the
00071      * default-network-interface-type configuration.  This will depend on the
00072      * target and the driver. For example a board may have its default setting
00073      * as "AUTO" which causes it to autodetect an Ethernet cable. This should
00074      * be described in the target's documentation.
00075      *
00076      * An application can override all target settings by implementing
00077      * NetworkInterface::get_default_instance() themselves - the default
00078      * definition is weak, and calls get_target_default_instance().
00079      */
00080     static NetworkInterface *get_default_instance();
00081 
00082     /** Get the local MAC address
00083      *
00084      *  Provided MAC address is intended for info or debug purposes and
00085      *  may not be provided if the underlying network interface does not
00086      *  provide a MAC address
00087      *  
00088      *  @return         Null-terminated representation of the local MAC address
00089      *                  or null if no MAC address is available
00090      */
00091     virtual const char *get_mac_address();
00092 
00093     /** Get the local IP address
00094      *
00095      *  @return         Null-terminated representation of the local IP address
00096      *                  or null if no IP address has been received
00097      */
00098     virtual const char *get_ip_address();
00099 
00100     /** Get the local network mask
00101      *
00102      *  @return         Null-terminated representation of the local network mask 
00103      *                  or null if no network mask has been received
00104      */
00105     virtual const char *get_netmask();
00106 
00107     /** Get the local gateway
00108      *
00109      *  @return         Null-terminated representation of the local gateway
00110      *                  or null if no network mask has been received
00111      */
00112     virtual const char *get_gateway();
00113 
00114     /** Set a static IP address
00115      *
00116      *  Configures this network interface to use a static IP address.
00117      *  Implicitly disables DHCP, which can be enabled in set_dhcp.
00118      *  Requires that the network is disconnected.
00119      *
00120      *  @param ip_address Null-terminated representation of the local IP address
00121      *  @param netmask    Null-terminated representation of the local network mask
00122      *  @param gateway    Null-terminated representation of the local gateway
00123      *  @return           0 on success, negative error code on failure
00124      */
00125     virtual nsapi_error_t set_network(
00126             const char *ip_address, const char *netmask, const char *gateway);
00127 
00128     /** Enable or disable DHCP on the network
00129      *
00130      *  Enables DHCP on connecting the network. Defaults to enabled unless
00131      *  a static IP address has been assigned. Requires that the network is
00132      *  disconnected.
00133      *
00134      *  @param dhcp     True to enable DHCP
00135      *  @return         0 on success, negative error code on failure
00136      */
00137     virtual nsapi_error_t set_dhcp(bool dhcp);
00138 
00139     /** Start the interface
00140      *
00141      *  @return     0 on success, negative error code on failure
00142      */
00143     virtual nsapi_error_t connect() = 0;
00144 
00145     /** Stop the interface
00146      *
00147      *  @return     0 on success, negative error code on failure
00148      */
00149     virtual nsapi_error_t disconnect() = 0;
00150 
00151     /** Translates a hostname to an IP address with specific version
00152      *
00153      *  The hostname may be either a domain name or an IP address. If the
00154      *  hostname is an IP address, no network transactions will be performed.
00155      *
00156      *  If no stack-specific DNS resolution is provided, the hostname
00157      *  will be resolve using a UDP socket on the stack.
00158      *
00159      *  @param host     Hostname to resolve
00160      *  @param address  Destination for the host SocketAddress
00161      *  @param version  IP version of address to resolve, NSAPI_UNSPEC indicates
00162      *                  version is chosen by the stack (defaults to NSAPI_UNSPEC)
00163      *  @return         0 on success, negative error code on failure
00164      */
00165     virtual nsapi_error_t gethostbyname(const char *host,
00166             SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC );
00167 
00168     /** Hostname translation callback (asynchronous)
00169      *
00170      *  Callback will be called after DNS resolution completes or a failure occurs.
00171      *
00172      *  Callback should not take more than 10ms to execute, otherwise it might
00173      *  prevent underlying thread processing. A portable user of the callback
00174      *  should not make calls to network operations due to stack size limitations.
00175      *  The callback should not perform expensive operations such as socket recv/send
00176      *  calls or blocking operations.
00177      *
00178      *  @param status  0 on success, negative error code on failure
00179      *  @param address On success, destination for the host SocketAddress
00180      */
00181     typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t;
00182 
00183     /** Translates a hostname to an IP address (asynchronous)
00184      *
00185      *  The hostname may be either a domain name or an IP address. If the
00186      *  hostname is an IP address, no network transactions will be performed.
00187      *
00188      *  If no stack-specific DNS resolution is provided, the hostname
00189      *  will be resolve using a UDP socket on the stack.
00190      *
00191      *  Call is non-blocking. Result of the DNS operation is returned by the callback.
00192      *  If this function returns failure, callback will not be called. In case result
00193      *  is success (IP address was found from DNS cache), callback will be called
00194      *  before function returns.
00195      *
00196      *  @param host     Hostname to resolve
00197      *  @param callback Callback that is called for result
00198      *  @param version  IP version of address to resolve, NSAPI_UNSPEC indicates
00199      *                  version is chosen by the stack (defaults to NSAPI_UNSPEC)
00200      *  @return         0 on immediate success,
00201      *                  negative error code on immediate failure or
00202      *                  a positive unique id that represents the hostname translation operation
00203      *                  and can be passed to cancel
00204      */
00205     virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback,
00206             nsapi_version_t version = NSAPI_UNSPEC );
00207 
00208     /** Cancels asynchronous hostname translation
00209      *
00210      *  When translation is cancelled, callback will not be called.
00211      *
00212      *  @param id       Unique id of the hostname translation operation
00213      *  @return         0 on success, negative error code on failure
00214      */
00215     virtual nsapi_error_t gethostbyname_async_cancel(int id);
00216 
00217     /** Add a domain name server to list of servers to query
00218      *
00219      *  @param address  Destination for the host address
00220      *  @return         0 on success, negative error code on failure
00221      */
00222     virtual nsapi_error_t add_dns_server(const SocketAddress &address);
00223 
00224     /** Register callback for status reporting
00225      *
00226      *  The specified status callback function will be called on status changes
00227      *  on the network. The parameters on the callback are the event type and
00228      *  event-type dependent reason parameter.
00229      *
00230      *  @param status_cb The callback for status changes
00231      */
00232     virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
00233 
00234     /** Get the connection status
00235      *
00236      *  @return         The connection status according to ConnectionStatusType
00237      */
00238     virtual nsapi_connection_status_t get_connection_status() const;
00239 
00240     /** Set blocking status of connect() which by default should be blocking
00241      *
00242      *  @param blocking true if connect is blocking
00243      *  @return         0 on success, negative error code on failure
00244      */
00245     virtual nsapi_error_t set_blocking(bool blocking);
00246 
00247     /** Dynamic downcast to an EthInterface */
00248     virtual EthInterface *ethInterface() {
00249         return 0;
00250     }
00251 
00252     /** Dynamic downcast to a WiFiInterface */
00253     virtual WiFiInterface *wifiInterface() {
00254         return 0;
00255     }
00256 
00257     /** Dynamic downcast to a MeshInterface */
00258     virtual MeshInterface *meshInterface() {
00259         return 0;
00260     }
00261 
00262     /** Dynamic downcast to a CellularBase */
00263     virtual CellularBase *cellularBase() {
00264         return 0;
00265     }
00266 
00267     /** Dynamic downcast to an EMACInterface */
00268     virtual EMACInterface *emacInterface() {
00269         return 0;
00270     }
00271 
00272 protected:
00273     friend class Socket;
00274     friend class UDPSocket;
00275     friend class TCPSocket;
00276     friend class TCPServer;
00277     friend class SocketAddress;
00278     template <typename IF>
00279     friend NetworkStack *nsapi_create_stack(IF *iface);
00280 
00281     /** Provide access to the NetworkStack object
00282      *
00283      *  @return The underlying NetworkStack object
00284      */
00285     virtual NetworkStack *get_stack() = 0;
00286 
00287     /** Get the target's default network instance.
00288      *
00289      * This method can be overridden by the target. Default implementations
00290      * are provided weakly by various subsystems as described in
00291      * NetworkInterface::get_default_instance(), so targets should not
00292      * need to override in simple cases.
00293      *
00294      * If a target has more elaborate interface selection, it can completely
00295      * override this behaviour by implementing
00296      * NetworkInterface::get_target_default_instance() themselves, either
00297      * unconditionally, or for a specific network-default-interface-type setting
00298      *
00299      * For example, a device with both Ethernet and Wi-fi could be set up its
00300      * target so that:
00301      *    * DEVICE_EMAC is set, and it provides EMAC::get_default_instance(),
00302      *      which means EthernetInterface provides EthInterface::get_target_instance()
00303      *      based on that EMAC.
00304      *    * It provides WifiInterface::get_target_default_instance().
00305      *    * The core will route NetworkInterface::get_default_instance() to
00306      *      either of those if network-default-interface-type is set to
00307      *      ETHERNET or WIFI.
00308      *    * The board overrides NetworkInterface::get_target_default_instance()
00309      *      if network-default-interface-type is set to AUTO. This returns
00310      *      either EthInterface::get_default_instance() or WiFIInterface::get_default_instance()
00311      *      depending on a cable detection.
00312      *
00313      *
00314      * performs the search described by get_default_instance.
00315      */
00316     static NetworkInterface *get_target_default_instance();
00317 };
00318 
00319 
00320 #endif