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 int set_network(const char *ip_address, const char *netmask, const char *gateway);
00082 
00083     /** Enable or disable DHCP on the network
00084      *
00085      *  Enables DHCP on connecting the network. Defaults to enabled unless
00086      *  a static IP address has been assigned. Requires that the network is
00087      *  disconnected.
00088      *
00089      *  @param dhcp     True to enable DHCP
00090      *  @return         0 on success, negative error code on failure
00091      */
00092     virtual int set_dhcp(bool dhcp);
00093 
00094     /** Start the interface
00095      *
00096      *  @return     0 on success, negative error code on failure
00097      */
00098     virtual int connect() = 0;
00099 
00100     /** Stop the interface
00101      *
00102      *  @return     0 on success, negative error code on failure
00103      */
00104     virtual int disconnect() = 0;
00105 
00106     /** Translates a hostname to an IP address
00107      *
00108      *  The hostname may be either a domain name or an IP address. If the
00109      *  hostname is an IP address, no network transactions will be performed.
00110      *
00111      *  If no stack-specific DNS resolution is provided, the hostname
00112      *  will be resolve using a UDP socket on the stack.
00113      *
00114      *  @param address  Destination for the host SocketAddress
00115      *  @param host     Hostname to resolve
00116      *  @return         0 on success, negative error code on failure
00117      */
00118     virtual int gethostbyname(const char *host, SocketAddress *address);
00119 
00120     /** Translates a hostname to an IP address with specific version
00121      *
00122      *  The hostname may be either a domain name or an IP address. If the
00123      *  hostname is an IP address, no network transactions will be performed.
00124      *
00125      *  If no stack-specific DNS resolution is provided, the hostname
00126      *  will be resolve using a UDP socket on the stack.
00127      *
00128      *  @param address  Destination for the host SocketAddress
00129      *  @param host     Hostname to resolve
00130      *  @param version  IP version of address to resolve
00131      *  @return         0 on success, negative error code on failure
00132      */
00133     virtual int gethostbyname(const char *host, SocketAddress *address, nsapi_version_t version);
00134 
00135     /** Add a domain name server to list of servers to query
00136      *
00137      *  @param addr     Destination for the host address
00138      *  @return         0 on success, negative error code on failure
00139      */
00140     virtual int add_dns_server(const SocketAddress &address);
00141 
00142 protected:
00143     friend class Socket;
00144     friend class UDPSocket;
00145     friend class TCPSocket;
00146     friend class TCPServer;
00147     friend class SocketAddress;
00148     template <typename IF>
00149     friend NetworkStack *nsapi_create_stack(IF *iface);
00150 
00151     /** Provide access to the NetworkStack object
00152      *
00153      *  @return The underlying NetworkStack object
00154      */
00155     virtual NetworkStack *get_stack() = 0;
00156 };
00157 
00158 
00159 #endif
00160 
00161 /** @}*/