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 
00024 // Predeclared class
00025 class NetworkStack;
00026 
00027 
00028 /** NetworkInterface class
00029  *
00030  *  Common interface that is shared between network devices
00031  *  @addtogroup netsocket
00032  */
00033 class NetworkInterface {
00034 public:
00035 
00036 
00037 
00038     virtual ~NetworkInterface() {};
00039 
00040     /** Get the local MAC address
00041      *
00042      *  Provided MAC address is intended for info or debug purposes and
00043      *  may not be provided if the underlying network interface does not
00044      *  provide a MAC address
00045      *  
00046      *  @return         Null-terminated representation of the local MAC address
00047      *                  or null if no MAC address is available
00048      */
00049     virtual const char *get_mac_address();
00050 
00051     /** Get the local IP address
00052      *
00053      *  @return         Null-terminated representation of the local IP address
00054      *                  or null if no IP address has been received
00055      */
00056     virtual const char *get_ip_address();
00057 
00058     /** Get the local network mask
00059      *
00060      *  @return         Null-terminated representation of the local network mask 
00061      *                  or null if no network mask has been received
00062      */
00063     virtual const char *get_netmask();
00064 
00065     /** Get the local gateway
00066      *
00067      *  @return         Null-terminated representation of the local gateway
00068      *                  or null if no network mask has been received
00069      */
00070     virtual const char *get_gateway();
00071 
00072     /** Set a static IP address
00073      *
00074      *  Configures this network interface to use a static IP address.
00075      *  Implicitly disables DHCP, which can be enabled in set_dhcp.
00076      *  Requires that the network is disconnected.
00077      *
00078      *  @param ip_address Null-terminated representation of the local IP address
00079      *  @param netmask    Null-terminated representation of the local network mask
00080      *  @param gateway    Null-terminated representation of the local gateway
00081      *  @return           0 on success, negative error code on failure
00082      */
00083     virtual nsapi_error_t set_network(
00084             const char *ip_address, const char *netmask, const char *gateway);
00085 
00086     /** Enable or disable DHCP on the network
00087      *
00088      *  Enables DHCP on connecting the network. Defaults to enabled unless
00089      *  a static IP address has been assigned. Requires that the network is
00090      *  disconnected.
00091      *
00092      *  @param dhcp     True to enable DHCP
00093      *  @return         0 on success, negative error code on failure
00094      */
00095     virtual nsapi_error_t set_dhcp(bool dhcp);
00096 
00097     /** Start the interface
00098      *
00099      *  @return     0 on success, negative error code on failure
00100      */
00101     virtual nsapi_error_t connect() = 0;
00102 
00103     /** Stop the interface
00104      *
00105      *  @return     0 on success, negative error code on failure
00106      */
00107     virtual nsapi_error_t disconnect() = 0;
00108 
00109     /** Translates a hostname to an IP address with specific version
00110      *
00111      *  The hostname may be either a domain name or an IP address. If the
00112      *  hostname is an IP address, no network transactions will be performed.
00113      *
00114      *  If no stack-specific DNS resolution is provided, the hostname
00115      *  will be resolve using a UDP socket on the stack.
00116      *
00117      *  @param address  Destination for the host SocketAddress
00118      *  @param host     Hostname to resolve
00119      *  @param version  IP version of address to resolve, NSAPI_UNSPEC indicates
00120      *                  version is chosen by the stack (defaults to NSAPI_UNSPEC)
00121      *  @return         0 on success, negative error code on failure
00122      */
00123     virtual nsapi_error_t gethostbyname(const char *host,
00124             SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC );
00125 
00126     /** Add a domain name server to list of servers to query
00127      *
00128      *  @param address  Destination for the host address
00129      *  @return         0 on success, negative error code on failure
00130      */
00131     virtual nsapi_error_t add_dns_server(const SocketAddress &address);
00132 
00133     /** Register callback for status reporting
00134      *
00135      *  The specified status callback function will be called on status changes
00136      *  on the network. The parameters on the callback are the event type and
00137      *  event-type dependent reason parameter.
00138      *
00139      *  @param status_cb The callback for status changes
00140      */
00141     virtual void attach(mbed::Callback<void(nsapi_event_t, intptr_t)> status_cb);
00142 
00143     /** Get the connection status
00144      *
00145      *  @return         The connection status according to ConnectionStatusType
00146      */
00147     virtual nsapi_connection_status_t get_connection_status() const;
00148 
00149     /** Set blocking status of connect() which by default should be blocking
00150      *
00151      *  @param blocking true if connect is blocking
00152      *  @return         0 on success, negative error code on failure
00153      */
00154     virtual nsapi_error_t set_blocking(bool blocking);
00155 
00156 
00157 protected:
00158     friend class Socket;
00159     friend class UDPSocket;
00160     friend class TCPSocket;
00161     friend class TCPServer;
00162     friend class SocketAddress;
00163     template <typename IF>
00164     friend NetworkStack *nsapi_create_stack(IF *iface);
00165 
00166     /** Provide access to the NetworkStack object
00167      *
00168      *  @return The underlying NetworkStack object
00169      */
00170     virtual NetworkStack *get_stack() = 0;
00171 };
00172 
00173 
00174 #endif