Simon Cooksey / mbed-os

Pinned to some recent date

features/netsocket/NetworkInterface.h@0:fb7af294d5d9, 2016-11-17 (annotated)

Committer:
Simon Cooksey
Date:
Thu Nov 17 16:43:53 2016 +0000
Revision:
0:fb7af294d5d9
Initial commit

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Simon Cooksey 0:fb7af294d5d9 1
Simon Cooksey 0:fb7af294d5d9 2 /** \addtogroup netsocket */
Simon Cooksey 0:fb7af294d5d9 3 /** @{*/
Simon Cooksey 0:fb7af294d5d9 4 /* NetworkStack
Simon Cooksey 0:fb7af294d5d9 5 * Copyright (c) 2015 ARM Limited
Simon Cooksey 0:fb7af294d5d9 6 *
Simon Cooksey 0:fb7af294d5d9 7 * Licensed under the Apache License, Version 2.0 (the "License");
Simon Cooksey 0:fb7af294d5d9 8 * you may not use this file except in compliance with the License.
Simon Cooksey 0:fb7af294d5d9 9 * You may obtain a copy of the License at
Simon Cooksey 0:fb7af294d5d9 10 *
Simon Cooksey 0:fb7af294d5d9 11 * http://www.apache.org/licenses/LICENSE-2.0
Simon Cooksey 0:fb7af294d5d9 12 *
Simon Cooksey 0:fb7af294d5d9 13 * Unless required by applicable law or agreed to in writing, software
Simon Cooksey 0:fb7af294d5d9 14 * distributed under the License is distributed on an "AS IS" BASIS,
Simon Cooksey 0:fb7af294d5d9 15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Simon Cooksey 0:fb7af294d5d9 16 * See the License for the specific language governing permissions and
Simon Cooksey 0:fb7af294d5d9 17 * limitations under the License.
Simon Cooksey 0:fb7af294d5d9 18 */
Simon Cooksey 0:fb7af294d5d9 19
Simon Cooksey 0:fb7af294d5d9 20 #ifndef NETWORK_INTERFACE_H
Simon Cooksey 0:fb7af294d5d9 21 #define NETWORK_INTERFACE_H
Simon Cooksey 0:fb7af294d5d9 22
Simon Cooksey 0:fb7af294d5d9 23 #include "netsocket/nsapi_types.h"
Simon Cooksey 0:fb7af294d5d9 24 #include "netsocket/SocketAddress.h"
Simon Cooksey 0:fb7af294d5d9 25
Simon Cooksey 0:fb7af294d5d9 26 // Predeclared class
Simon Cooksey 0:fb7af294d5d9 27 class NetworkStack;
Simon Cooksey 0:fb7af294d5d9 28
Simon Cooksey 0:fb7af294d5d9 29
Simon Cooksey 0:fb7af294d5d9 30 /** NetworkInterface class
Simon Cooksey 0:fb7af294d5d9 31 *
Simon Cooksey 0:fb7af294d5d9 32 * Common interface that is shared between network devices
Simon Cooksey 0:fb7af294d5d9 33 */
Simon Cooksey 0:fb7af294d5d9 34 class NetworkInterface {
Simon Cooksey 0:fb7af294d5d9 35 public:
Simon Cooksey 0:fb7af294d5d9 36 virtual ~NetworkInterface() {};
Simon Cooksey 0:fb7af294d5d9 37
Simon Cooksey 0:fb7af294d5d9 38 /** Get the local MAC address
Simon Cooksey 0:fb7af294d5d9 39 *
Simon Cooksey 0:fb7af294d5d9 40 * Provided MAC address is intended for info or debug purposes and
Simon Cooksey 0:fb7af294d5d9 41 * may not be provided if the underlying network interface does not
Simon Cooksey 0:fb7af294d5d9 42 * provide a MAC address
Simon Cooksey 0:fb7af294d5d9 43 *
Simon Cooksey 0:fb7af294d5d9 44 * @return Null-terminated representation of the local MAC address
Simon Cooksey 0:fb7af294d5d9 45 * or null if no MAC address is available
Simon Cooksey 0:fb7af294d5d9 46 */
Simon Cooksey 0:fb7af294d5d9 47 virtual const char *get_mac_address();
Simon Cooksey 0:fb7af294d5d9 48
Simon Cooksey 0:fb7af294d5d9 49 /** Get the local IP address
Simon Cooksey 0:fb7af294d5d9 50 *
Simon Cooksey 0:fb7af294d5d9 51 * @return Null-terminated representation of the local IP address
Simon Cooksey 0:fb7af294d5d9 52 * or null if no IP address has been recieved
Simon Cooksey 0:fb7af294d5d9 53 */
Simon Cooksey 0:fb7af294d5d9 54 virtual const char *get_ip_address();
Simon Cooksey 0:fb7af294d5d9 55
Simon Cooksey 0:fb7af294d5d9 56 /** Get the local network mask
Simon Cooksey 0:fb7af294d5d9 57 *
Simon Cooksey 0:fb7af294d5d9 58 * @return Null-terminated representation of the local network mask
Simon Cooksey 0:fb7af294d5d9 59 * or null if no network mask has been recieved
Simon Cooksey 0:fb7af294d5d9 60 */
Simon Cooksey 0:fb7af294d5d9 61 virtual const char *get_netmask();
Simon Cooksey 0:fb7af294d5d9 62
Simon Cooksey 0:fb7af294d5d9 63 /** Get the local gateway
Simon Cooksey 0:fb7af294d5d9 64 *
Simon Cooksey 0:fb7af294d5d9 65 * @return Null-terminated representation of the local gateway
Simon Cooksey 0:fb7af294d5d9 66 * or null if no network mask has been recieved
Simon Cooksey 0:fb7af294d5d9 67 */
Simon Cooksey 0:fb7af294d5d9 68 virtual const char *get_gateway();
Simon Cooksey 0:fb7af294d5d9 69
Simon Cooksey 0:fb7af294d5d9 70 /** Set a static IP address
Simon Cooksey 0:fb7af294d5d9 71 *
Simon Cooksey 0:fb7af294d5d9 72 * Configures this network interface to use a static IP address.
Simon Cooksey 0:fb7af294d5d9 73 * Implicitly disables DHCP, which can be enabled in set_dhcp.
Simon Cooksey 0:fb7af294d5d9 74 * Requires that the network is disconnected.
Simon Cooksey 0:fb7af294d5d9 75 *
Simon Cooksey 0:fb7af294d5d9 76 * @param address Null-terminated representation of the local IP address
Simon Cooksey 0:fb7af294d5d9 77 * @param netmask Null-terminated representation of the local network mask
Simon Cooksey 0:fb7af294d5d9 78 * @param gateway Null-terminated representation of the local gateway
Simon Cooksey 0:fb7af294d5d9 79 * @return 0 on success, negative error code on failure
Simon Cooksey 0:fb7af294d5d9 80 */
Simon Cooksey 0:fb7af294d5d9 81 virtual int set_network(const char *ip_address, const char *netmask, const char *gateway);
Simon Cooksey 0:fb7af294d5d9 82
Simon Cooksey 0:fb7af294d5d9 83 /** Enable or disable DHCP on the network
Simon Cooksey 0:fb7af294d5d9 84 *
Simon Cooksey 0:fb7af294d5d9 85 * Enables DHCP on connecting the network. Defaults to enabled unless
Simon Cooksey 0:fb7af294d5d9 86 * a static IP address has been assigned. Requires that the network is
Simon Cooksey 0:fb7af294d5d9 87 * disconnected.
Simon Cooksey 0:fb7af294d5d9 88 *
Simon Cooksey 0:fb7af294d5d9 89 * @param dhcp True to enable DHCP
Simon Cooksey 0:fb7af294d5d9 90 * @return 0 on success, negative error code on failure
Simon Cooksey 0:fb7af294d5d9 91 */
Simon Cooksey 0:fb7af294d5d9 92 virtual int set_dhcp(bool dhcp);
Simon Cooksey 0:fb7af294d5d9 93
Simon Cooksey 0:fb7af294d5d9 94 /** Start the interface
Simon Cooksey 0:fb7af294d5d9 95 *
Simon Cooksey 0:fb7af294d5d9 96 * @return 0 on success, negative error code on failure
Simon Cooksey 0:fb7af294d5d9 97 */
Simon Cooksey 0:fb7af294d5d9 98 virtual int connect() = 0;
Simon Cooksey 0:fb7af294d5d9 99
Simon Cooksey 0:fb7af294d5d9 100 /** Stop the interface
Simon Cooksey 0:fb7af294d5d9 101 *
Simon Cooksey 0:fb7af294d5d9 102 * @return 0 on success, negative error code on failure
Simon Cooksey 0:fb7af294d5d9 103 */
Simon Cooksey 0:fb7af294d5d9 104 virtual int disconnect() = 0;
Simon Cooksey 0:fb7af294d5d9 105
Simon Cooksey 0:fb7af294d5d9 106 /** Translates a hostname to an IP address with specific version
Simon Cooksey 0:fb7af294d5d9 107 *
Simon Cooksey 0:fb7af294d5d9 108 * The hostname may be either a domain name or an IP address. If the
Simon Cooksey 0:fb7af294d5d9 109 * hostname is an IP address, no network transactions will be performed.
Simon Cooksey 0:fb7af294d5d9 110 *
Simon Cooksey 0:fb7af294d5d9 111 * If no stack-specific DNS resolution is provided, the hostname
Simon Cooksey 0:fb7af294d5d9 112 * will be resolve using a UDP socket on the stack.
Simon Cooksey 0:fb7af294d5d9 113 *
Simon Cooksey 0:fb7af294d5d9 114 * @param address Destination for the host SocketAddress
Simon Cooksey 0:fb7af294d5d9 115 * @param host Hostname to resolve
Simon Cooksey 0:fb7af294d5d9 116 * @param version IP version of address to resolve, NSAPI_UNSPEC indicates
Simon Cooksey 0:fb7af294d5d9 117 * version is chosen by the stack (defaults to NSAPI_UNSPEC)
Simon Cooksey 0:fb7af294d5d9 118 * @return 0 on success, negative error code on failure
Simon Cooksey 0:fb7af294d5d9 119 */
Simon Cooksey 0:fb7af294d5d9 120 virtual int gethostbyname(const char *host, SocketAddress *address, nsapi_version_t version = NSAPI_UNSPEC);
Simon Cooksey 0:fb7af294d5d9 121
Simon Cooksey 0:fb7af294d5d9 122 /** Add a domain name server to list of servers to query
Simon Cooksey 0:fb7af294d5d9 123 *
Simon Cooksey 0:fb7af294d5d9 124 * @param addr Destination for the host address
Simon Cooksey 0:fb7af294d5d9 125 * @return 0 on success, negative error code on failure
Simon Cooksey 0:fb7af294d5d9 126 */
Simon Cooksey 0:fb7af294d5d9 127 virtual int add_dns_server(const SocketAddress &address);
Simon Cooksey 0:fb7af294d5d9 128
Simon Cooksey 0:fb7af294d5d9 129 protected:
Simon Cooksey 0:fb7af294d5d9 130 friend class Socket;
Simon Cooksey 0:fb7af294d5d9 131 friend class UDPSocket;
Simon Cooksey 0:fb7af294d5d9 132 friend class TCPSocket;
Simon Cooksey 0:fb7af294d5d9 133 friend class TCPServer;
Simon Cooksey 0:fb7af294d5d9 134 friend class SocketAddress;
Simon Cooksey 0:fb7af294d5d9 135 template <typename IF>
Simon Cooksey 0:fb7af294d5d9 136 friend NetworkStack *nsapi_create_stack(IF *iface);
Simon Cooksey 0:fb7af294d5d9 137
Simon Cooksey 0:fb7af294d5d9 138 /** Provide access to the NetworkStack object
Simon Cooksey 0:fb7af294d5d9 139 *
Simon Cooksey 0:fb7af294d5d9 140 * @return The underlying NetworkStack object
Simon Cooksey 0:fb7af294d5d9 141 */
Simon Cooksey 0:fb7af294d5d9 142 virtual NetworkStack *get_stack() = 0;
Simon Cooksey 0:fb7af294d5d9 143 };
Simon Cooksey 0:fb7af294d5d9 144
Simon Cooksey 0:fb7af294d5d9 145
Simon Cooksey 0:fb7af294d5d9 146 #endif
Simon Cooksey 0:fb7af294d5d9 147
Simon Cooksey 0:fb7af294d5d9 148 /** @}*/