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(const char *ip_address, const char *netmask, const char *gateway);
00126 
00127     /** Enable or disable DHCP on the network
00128      *
00129      *  Enables DHCP on connecting the network. Defaults to enabled unless
00130      *  a static IP address has been assigned. Requires that the network is
00131      *  disconnected.
00132      *
00133      *  @param dhcp     True to enable DHCP
00134      *  @return         0 on success, negative error code on failure
00135      */
00136     virtual nsapi_error_t set_dhcp(bool dhcp);
00137 
00138     /** Start the interface
00139      *
00140      *  @return     0 on success, negative error code on failure
00141      */
00142     virtual nsapi_error_t connect() = 0;
00143 
00144     /** Stop the interface
00145      *
00146      *  @return     0 on success, negative error code on failure
00147      */
00148     virtual nsapi_error_t disconnect() = 0;
00149 
00150     /** Translates a hostname to an IP address with specific version
00151      *
00152      *  The hostname may be either a domain name or an IP address. If the
00153      *  hostname is an IP address, no network transactions will be performed.
00154      *
00155      *  If no stack-specific DNS resolution is provided, the hostname
00156      *  will be resolve using a UDP socket on the stack.
00157      *
00158      *  @param host     Hostname to resolve
00159      *  @param address  Destination for the host SocketAddress
00160      *  @param version  IP version of address to resolve, NSAPI_UNSPEC indicates
00161      *                  version is chosen by the stack (defaults to NSAPI_UNSPEC)
00162      *  @return         0 on success, negative error code on failure
00163      */
00164     virtual nsapi_error_t gethostbyname(const char *host,
00165                                         SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC );
00166 
00167     /** Hostname translation callback (asynchronous)
00168      *
00169      *  Callback will be called after DNS resolution completes or a failure occurs.
00170      *
00171      *  Callback should not take more than 10ms to execute, otherwise it might
00172      *  prevent underlying thread processing. A portable user of the callback
00173      *  should not make calls to network operations due to stack size limitations.
00174      *  The callback should not perform expensive operations such as socket recv/send
00175      *  calls or blocking operations.
00176      *
00177      *  @param status  0 on success, negative error code on failure
00178      *  @param address On success, destination for the host SocketAddress
00179      */
00180     typedef mbed::Callback<void (nsapi_error_t result, SocketAddress *address)> hostbyname_cb_t;
00181 
00182     /** Translates a hostname to an IP address (asynchronous)
00183      *
00184      *  The hostname may be either a domain name or an IP address. If the
00185      *  hostname is an IP address, no network transactions will be performed.
00186      *
00187      *  If no stack-specific DNS resolution is provided, the hostname
00188      *  will be resolve using a UDP socket on the stack.
00189      *
00190      *  Call is non-blocking. Result of the DNS operation is returned by the callback.
00191      *  If this function returns failure, callback will not be called. In case result
00192      *  is success (IP address was found from DNS cache), callback will be called
00193      *  before function returns.
00194      *
00195      *  @param host     Hostname to resolve
00196      *  @param callback Callback that is called for result
00197      *  @param version  IP version of address to resolve, NSAPI_UNSPEC indicates
00198      *                  version is chosen by the stack (defaults to NSAPI_UNSPEC)
00199      *  @return         0 on immediate success,
00200      *                  negative error code on immediate failure or
00201      *                  a positive unique id that represents the hostname translation operation
00202      *                  and can be passed to cancel
00203      */
00204     virtual nsapi_value_or_error_t gethostbyname_async(const char *host, hostbyname_cb_t callback,
00205                                                        nsapi_version_t version = NSAPI_UNSPEC );
00206 
00207     /** Cancels asynchronous hostname translation
00208      *
00209      *  When translation is cancelled, callback will not be called.
00210      *
00211      *  @param id       Unique id of the hostname translation operation
00212      *  @return         0 on success, negative error code on failure
00213      */
00214     virtual nsapi_error_t gethostbyname_async_cancel(int id);
00215 
00216     /** Add a domain name server to list of servers to query
00217      *
00218      *  @param address  Destination for the host address
00219      *  @return         0 on success, negative error code on failure
00220      */
00221     virtual nsapi_error_t add_dns_server(const SocketAddress &address);
00222 
00223     /** Register callback for status reporting
00224      *
00225      *  The specified status callback function will be called on status changes
00226      *  on the network. The parameters on the callback are the event type and
00227      *  event-type dependent reason parameter.
00228      *
00229      *  @param status_cb The callback for status changes
00230      */
00231     virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
00232 
00233     /** Get the connection status
00234      *
00235      *  @return         The connection status according to ConnectionStatusType
00236      */
00237     virtual nsapi_connection_status_t get_connection_status() const;
00238 
00239     /** Set blocking status of connect() which by default should be blocking
00240      *
00241      *  @param blocking true if connect is blocking
00242      *  @return         0 on success, negative error code on failure
00243      */
00244     virtual nsapi_error_t set_blocking(bool blocking);
00245 
00246     /** Dynamic downcast to an EthInterface */
00247     virtual EthInterface *ethInterface()
00248     {
00249         return 0;
00250     }
00251 
00252     /** Dynamic downcast to a WiFiInterface */
00253     virtual WiFiInterface *wifiInterface()
00254     {
00255         return 0;
00256     }
00257 
00258     /** Dynamic downcast to a MeshInterface */
00259     virtual MeshInterface *meshInterface()
00260     {
00261         return 0;
00262     }
00263 
00264     /** Dynamic downcast to a CellularBase */
00265     virtual CellularBase *cellularBase()
00266     {
00267         return 0;
00268     }
00269 
00270     /** Dynamic downcast to an EMACInterface */
00271     virtual EMACInterface *emacInterface()
00272     {
00273         return 0;
00274     }
00275 
00276 protected:
00277     friend class InternetSocket;
00278     friend class UDPSocket;
00279     friend class TCPSocket;
00280     friend class TCPServer;
00281     friend class SocketAddress;
00282     template <typename IF>
00283     friend NetworkStack *nsapi_create_stack(IF *iface);
00284 
00285     /** Provide access to the NetworkStack object
00286      *
00287      *  @return The underlying NetworkStack object
00288      */
00289     virtual NetworkStack *get_stack() = 0;
00290 
00291     /** Get the target's default network instance.
00292      *
00293      * This method can be overridden by the target. Default implementations
00294      * are provided weakly by various subsystems as described in
00295      * NetworkInterface::get_default_instance(), so targets should not
00296      * need to override in simple cases.
00297      *
00298      * If a target has more elaborate interface selection, it can completely
00299      * override this behaviour by implementing
00300      * NetworkInterface::get_target_default_instance() themselves, either
00301      * unconditionally, or for a specific network-default-interface-type setting
00302      *
00303      * For example, a device with both Ethernet and Wi-fi could be set up its
00304      * target so that:
00305      *    * DEVICE_EMAC is set, and it provides EMAC::get_default_instance(),
00306      *      which means EthernetInterface provides EthInterface::get_target_instance()
00307      *      based on that EMAC.
00308      *    * It provides WifiInterface::get_target_default_instance().
00309      *    * The core will route NetworkInterface::get_default_instance() to
00310      *      either of those if network-default-interface-type is set to
00311      *      ETHERNET or WIFI.
00312      *    * The board overrides NetworkInterface::get_target_default_instance()
00313      *      if network-default-interface-type is set to AUTO. This returns
00314      *      either EthInterface::get_default_instance() or WiFIInterface::get_default_instance()
00315      *      depending on a cable detection.
00316      *
00317      *
00318      * performs the search described by get_default_instance.
00319      */
00320     static NetworkInterface *get_target_default_instance();
00321 };
00322 
00323 
00324 #endif