NetworkInterface.h

00001 
00002 /** \addtogroup netsocket */
00003 /** @{*/
00004 /* NetworkStack
00005  * Copyright (c) 2015 ARM Limited
00006  *
00007  * Licensed under the Apache License, Version 2.0 (the "License");
00008  * you may not use this file except in compliance with the License.
00009  * You may obtain a copy of the License at
00010  *
00011  *     http://www.apache.org/licenses/LICENSE-2.0
00012  *
00013  * Unless required by applicable law or agreed to in writing, software
00014  * distributed under the License is distributed on an "AS IS" BASIS,
00015  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00016  * See the License for the specific language governing permissions and
00017  * limitations under the License.
00018  */
00019 
00020 #ifndef NETWORK_INTERFACE_H
00021 #define NETWORK_INTERFACE_H
00022 
00023 #include "netsocket/nsapi_types.h"
00024 #include "netsocket/SocketAddress.h"
00025 
00026 // Predeclared class
00027 class NetworkStack;
00028 
00029 
00030 /** NetworkInterface class
00031  *
00032  *  Common interface that is shared between network devices
00033  */
00034 class NetworkInterface {
00035 public:
00036     virtual ~NetworkInterface() {};
00037 
00038     /** Get the local MAC address
00039      *
00040      *  Provided MAC address is intended for info or debug purposes and
00041      *  may not be provided if the underlying network interface does not
00042      *  provide a MAC address
00043      *  
00044      *  @return         Null-terminated representation of the local MAC address
00045      *                  or null if no MAC address is available
00046      */
00047     virtual const char *get_mac_address();
00048 
00049     /** Get the local IP address
00050      *
00051      *  @return         Null-terminated representation of the local IP address
00052      *                  or null if no IP address has been recieved
00053      */
00054     virtual const char *get_ip_address();
00055 
00056     /** Get the local network mask
00057      *
00058      *  @return         Null-terminated representation of the local network mask 
00059      *                  or null if no network mask has been recieved
00060      */
00061     virtual const char *get_netmask();
00062 
00063     /** Get the local gateway
00064      *
00065      *  @return         Null-terminated representation of the local gateway
00066      *                  or null if no network mask has been recieved
00067      */
00068     virtual const char *get_gateway();
00069 
00070     /** Set a static IP address
00071      *
00072      *  Configures this network interface to use a static IP address.
00073      *  Implicitly disables DHCP, which can be enabled in set_dhcp.
00074      *  Requires that the network is disconnected.
00075      *
00076      *  @param address  Null-terminated representation of the local IP address
00077      *  @param netmask  Null-terminated representation of the local network mask
00078      *  @param gateway  Null-terminated representation of the local gateway
00079      *  @return         0 on success, negative error code on failure
00080      */
00081     virtual nsapi_error_t set_network(
00082             const char *ip_address, const char *netmask, const char *gateway);
00083 
00084     /** Enable or disable DHCP on the network
00085      *
00086      *  Enables DHCP on connecting the network. Defaults to enabled unless
00087      *  a static IP address has been assigned. Requires that the network is
00088      *  disconnected.
00089      *
00090      *  @param dhcp     True to enable DHCP
00091      *  @return         0 on success, negative error code on failure
00092      */
00093     virtual nsapi_error_t set_dhcp(bool dhcp);
00094 
00095     /** Start the interface
00096      *
00097      *  @return     0 on success, negative error code on failure
00098      */
00099     virtual nsapi_error_t connect() = 0;
00100 
00101     /** Stop the interface
00102      *
00103      *  @return     0 on success, negative error code on failure
00104      */
00105     virtual nsapi_error_t disconnect() = 0;
00106 
00107     /** Translates a hostname to an IP address with specific version
00108      *
00109      *  The hostname may be either a domain name or an IP address. If the
00110      *  hostname is an IP address, no network transactions will be performed.
00111      *
00112      *  If no stack-specific DNS resolution is provided, the hostname
00113      *  will be resolve using a UDP socket on the stack.
00114      *
00115      *  @param address  Destination for the host SocketAddress
00116      *  @param host     Hostname to resolve
00117      *  @param version  IP version of address to resolve, NSAPI_UNSPEC indicates
00118      *                  version is chosen by the stack (defaults to NSAPI_UNSPEC)
00119      *  @return         0 on success, negative error code on failure
00120      */
00121     virtual nsapi_error_t gethostbyname(const char *host,
00122             SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC );
00123 
00124     /** Add a domain name server to list of servers to query
00125      *
00126      *  @param addr     Destination for the host address
00127      *  @return         0 on success, negative error code on failure
00128      */
00129     virtual nsapi_error_t add_dns_server(const SocketAddress &address);
00130 
00131 protected:
00132     friend class Socket;
00133     friend class UDPSocket;
00134     friend class TCPSocket;
00135     friend class TCPServer;
00136     friend class SocketAddress;
00137     template <typename IF>
00138     friend NetworkStack *nsapi_create_stack(IF *iface);
00139 
00140     /** Provide access to the NetworkStack object
00141      *
00142      *  @return The underlying NetworkStack object
00143      */
00144     virtual NetworkStack *get_stack() = 0;
00145 };
00146 
00147 
00148 #endif
00149 
00150 /** @}*/