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