NetworkSocketAPI / NetworkSocketAPI

Base class for IP Based Networking Libraries

Dependencies:   DnsQuery

Dependents:   TempTower BSDInterfaceTests HelloBSDInterface ESP8266InterfaceTests ... more

For a complete getting started guide see the wiki...

Network Socket API

The Network Socket API provides a common interface for using sockets on network devices. The API provides a simple class-based interface that should be familiar to users experienced with other socket APIs. Additionally, the API provides a simple interface for implementing network devices, making it easy to connect hardware agnostic programs to new devices.

Network Interfaces

The NetworkInterface provides an abstract class for network devices that support sockets. Devices should provide a DeviceInterface class that inherits this interface and adds implementation specific methods for using the device. A NetworkInterface must be provided to a Socket constructor to open a socket on the interface. Currently two subclasses are defined for common devices, EthernetInterface and WiFiInterface.

Sockets

The Socket class is used for managing network sockets. Once opened, the socket provides a pipe through which data can sent and recieved to a specific endpoint. The socket class can be instantiated as either a TCPSocket or a UDPSocket which defines the protocol used for the connection.

SocketAddress.h@104:d28d8b508e7c, 2016-04-19 (annotated)

Committer:
Christopher Haster
Date:
Tue Apr 19 18:26:21 2016 -0500
Revision:
104:d28d8b508e7c
Parent:
94:644df37bb05b
Child:
105:2fd212f8da61
Revised documentation for Interface classes

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Christopher Haster 104:d28d8b508e7c 1 /* SocketAddress
Christopher Haster 89:b1d417383c0d 2 * Copyright (c) 2015 ARM Limited
Christopher Haster 89:b1d417383c0d 3 *
Christopher Haster 89:b1d417383c0d 4 * Licensed under the Apache License, Version 2.0 (the "License");
Christopher Haster 89:b1d417383c0d 5 * you may not use this file except in compliance with the License.
Christopher Haster 89:b1d417383c0d 6 * You may obtain a copy of the License at
Christopher Haster 89:b1d417383c0d 7 *
Christopher Haster 89:b1d417383c0d 8 * http://www.apache.org/licenses/LICENSE-2.0
Christopher Haster 89:b1d417383c0d 9 *
Christopher Haster 89:b1d417383c0d 10 * Unless required by applicable law or agreed to in writing, software
Christopher Haster 89:b1d417383c0d 11 * distributed under the License is distributed on an "AS IS" BASIS,
Christopher Haster 89:b1d417383c0d 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Christopher Haster 89:b1d417383c0d 13 * See the License for the specific language governing permissions and
Christopher Haster 89:b1d417383c0d 14 * limitations under the License.
Christopher Haster 89:b1d417383c0d 15 */
Christopher Haster 89:b1d417383c0d 16
Christopher Haster 89:b1d417383c0d 17 #ifndef SOCKET_ADDRESS_H
Christopher Haster 89:b1d417383c0d 18 #define SOCKET_ADDRESS_H
Christopher Haster 89:b1d417383c0d 19
Christopher Haster 89:b1d417383c0d 20 #include <stdint.h>
Christopher Haster 89:b1d417383c0d 21
Christopher Haster 94:644df37bb05b 22
Christopher Haster 94:644df37bb05b 23 /** Maximum size of IP address representation
Christopher Haster 94:644df37bb05b 24 */
Christopher Haster 94:644df37bb05b 25 #define NSAPI_IP_SIZE NSAPI_IPv6_SIZE
Christopher Haster 94:644df37bb05b 26
Christopher Haster 94:644df37bb05b 27 /** Maximum number of bytes for IP address
Christopher Haster 94:644df37bb05b 28 */
Christopher Haster 94:644df37bb05b 29 #define NSAPI_IP_BYTES NSAPI_IPv6_BYTES
Christopher Haster 89:b1d417383c0d 30
Christopher Haster 104:d28d8b508e7c 31 /** Enum of IP address versions
Christopher Haster 104:d28d8b508e7c 32 *
Christopher Haster 104:d28d8b508e7c 33 * The IP version specifies the type of an IP address.
Christopher Haster 104:d28d8b508e7c 34 *
Christopher Haster 104:d28d8b508e7c 35 * @enum nsapi_version_t
Christopher Haster 94:644df37bb05b 36 */
Christopher Haster 94:644df37bb05b 37 enum nsapi_version_t {
Christopher Haster 94:644df37bb05b 38 NSAPI_IPv4, /*!< Address is IPv4 */
Christopher Haster 94:644df37bb05b 39 NSAPI_IPv6, /*!< Address is IPv6 */
Christopher Haster 94:644df37bb05b 40 };
Christopher Haster 94:644df37bb05b 41
Christopher Haster 94:644df37bb05b 42 /** Size of IPv4 representation
Christopher Haster 94:644df37bb05b 43 */
Christopher Haster 94:644df37bb05b 44 #define NSAPI_IPv4_SIZE 16
Christopher Haster 94:644df37bb05b 45
Christopher Haster 94:644df37bb05b 46 /** Number of bytes in IPv4 address
Christopher Haster 94:644df37bb05b 47 */
Christopher Haster 94:644df37bb05b 48 #define NSAPI_IPv4_BYTES 4
Christopher Haster 94:644df37bb05b 49
Christopher Haster 94:644df37bb05b 50 /** Size of IPv6 representation
Christopher Haster 94:644df37bb05b 51 */
Christopher Haster 94:644df37bb05b 52 #define NSAPI_IPv6_SIZE 40
Christopher Haster 94:644df37bb05b 53
Christopher Haster 94:644df37bb05b 54 /** Number of bytes in IPv6 address
Christopher Haster 94:644df37bb05b 55 */
Christopher Haster 94:644df37bb05b 56 #define NSAPI_IPv6_BYTES 16
Christopher Haster 89:b1d417383c0d 57
Christopher Haster 89:b1d417383c0d 58 // Predeclared classes
Christopher Haster 89:b1d417383c0d 59 class NetworkInterface;
Christopher Haster 89:b1d417383c0d 60
Christopher Haster 94:644df37bb05b 61
Christopher Haster 104:d28d8b508e7c 62 /** SocketAddress class
Christopher Haster 104:d28d8b508e7c 63 *
Christopher Haster 104:d28d8b508e7c 64 * Representation of an IP address and port pair.
Christopher Haster 89:b1d417383c0d 65 */
Christopher Haster 89:b1d417383c0d 66 class SocketAddress {
Christopher Haster 89:b1d417383c0d 67 public:
Christopher Haster 104:d28d8b508e7c 68 /** Create a SocketAddress from a hostname and port
Christopher Haster 104:d28d8b508e7c 69 *
Christopher Haster 104:d28d8b508e7c 70 * The hostname may be either a domain name or an IP address. If the
Christopher Haster 104:d28d8b508e7c 71 * hostname is an IP address, no network transactions will be performed.
Christopher Haster 104:d28d8b508e7c 72 *
Christopher Haster 104:d28d8b508e7c 73 * On failure, the IP address and port will be set to zero
Christopher Haster 104:d28d8b508e7c 74 *
Christopher Haster 104:d28d8b508e7c 75 * @param iface Network stack to use for DNS resolution
Christopher Haster 104:d28d8b508e7c 76 * @param host Hostname to resolve
Christopher Haster 94:644df37bb05b 77 * @param port Optional 16-bit port
Christopher Haster 89:b1d417383c0d 78 */
Christopher Haster 104:d28d8b508e7c 79 SocketAddress(NetworkInterface *iface, const char *host, uint16_t port = 0);
Christopher Haster 89:b1d417383c0d 80
Christopher Haster 104:d28d8b508e7c 81 /** Create a SocketAddress from an IP address and port
Christopher Haster 104:d28d8b508e7c 82 *
Christopher Haster 104:d28d8b508e7c 83 * @param host Null-terminated representation of the IP address
Christopher Haster 94:644df37bb05b 84 * @param port Optional 16-bit port
Christopher Haster 89:b1d417383c0d 85 */
Christopher Haster 89:b1d417383c0d 86 SocketAddress(const char *addr = 0, uint16_t port = 0);
Christopher Haster 89:b1d417383c0d 87
Christopher Haster 104:d28d8b508e7c 88 /** Create a SocketAddress from a raw IP address and port
Christopher Haster 104:d28d8b508e7c 89 *
Christopher Haster 104:d28d8b508e7c 90 * @param bytes Raw IP address in big-endian order
Christopher Haster 94:644df37bb05b 91 * @param version IP address version, NSAPI_IPv4 or NSAPI_IPv6
Christopher Haster 94:644df37bb05b 92 * @param port Optional 16-bit port
Christopher Haster 94:644df37bb05b 93 */
Christopher Haster 94:644df37bb05b 94 SocketAddress(const void *bytes, nsapi_version_t version, uint16_t port = 0);
Christopher Haster 94:644df37bb05b 95
Christopher Haster 104:d28d8b508e7c 96 /** Create a SocketAddress from another SocketAddress
Christopher Haster 104:d28d8b508e7c 97 *
Christopher Haster 104:d28d8b508e7c 98 * @param address SocketAddress to copy
Christopher Haster 89:b1d417383c0d 99 */
Christopher Haster 89:b1d417383c0d 100 SocketAddress(const SocketAddress &addr);
Christopher Haster 89:b1d417383c0d 101
Christopher Haster 89:b1d417383c0d 102 /** Set the IP address
Christopher Haster 104:d28d8b508e7c 103 *
Christopher Haster 104:d28d8b508e7c 104 * @param addr Null-terminated represention of the IP address
Christopher Haster 89:b1d417383c0d 105 */
Christopher Haster 89:b1d417383c0d 106 void set_ip_address(const char *addr);
Christopher Haster 89:b1d417383c0d 107
Christopher Haster 104:d28d8b508e7c 108 /** Set the raw IP address
Christopher Haster 104:d28d8b508e7c 109 *
Christopher Haster 104:d28d8b508e7c 110 * @param bytes Raw IP address in big-endian order
Christopher Haster 94:644df37bb05b 111 * @param version IP address version, NSAPI_IPv4 or NSAPI_IPv6
Christopher Haster 94:644df37bb05b 112 */
Christopher Haster 94:644df37bb05b 113 void set_ip_bytes(const void *bytes, nsapi_version_t version);
Christopher Haster 94:644df37bb05b 114
Christopher Haster 89:b1d417383c0d 115 /** Set the port
Christopher Haster 104:d28d8b508e7c 116 *
Christopher Haster 94:644df37bb05b 117 * @param port 16-bit port
Christopher Haster 89:b1d417383c0d 118 */
Christopher Haster 89:b1d417383c0d 119 void set_port(uint16_t port);
Christopher Haster 89:b1d417383c0d 120
Christopher Haster 89:b1d417383c0d 121 /** Get the IP address
Christopher Haster 104:d28d8b508e7c 122 *
Christopher Haster 104:d28d8b508e7c 123 * @return Null-terminated representation of the IP Address
Christopher Haster 89:b1d417383c0d 124 */
Christopher Haster 89:b1d417383c0d 125 const char *get_ip_address() const;
Christopher Haster 94:644df37bb05b 126
Christopher Haster 104:d28d8b508e7c 127 /** Get the raw IP address
Christopher Haster 104:d28d8b508e7c 128 *
Christopher Haster 104:d28d8b508e7c 129 * @return Raw IP address in big-endian order
Christopher Haster 94:644df37bb05b 130 */
Christopher Haster 94:644df37bb05b 131 const void *get_ip_bytes() const;
Christopher Haster 94:644df37bb05b 132
Christopher Haster 104:d28d8b508e7c 133 /** Get the IP address version
Christopher Haster 104:d28d8b508e7c 134 *
Christopher Haster 94:644df37bb05b 135 * @return IP address version, NSAPI_IPv4 or NSAPI_IPv6
Christopher Haster 94:644df37bb05b 136 */
Christopher Haster 94:644df37bb05b 137 nsapi_version_t get_ip_version() const;
Christopher Haster 89:b1d417383c0d 138
Christopher Haster 89:b1d417383c0d 139 /** Get the port
Christopher Haster 104:d28d8b508e7c 140 *
Christopher Haster 94:644df37bb05b 141 * @return The 16-bit port
Christopher Haster 89:b1d417383c0d 142 */
Christopher Haster 94:644df37bb05b 143 uint16_t get_port() const;
Christopher Haster 94:644df37bb05b 144
Christopher Haster 104:d28d8b508e7c 145 /** Test if address is zero
Christopher Haster 104:d28d8b508e7c 146 *
Christopher Haster 104:d28d8b508e7c 147 * @return True if address is not zero
Christopher Haster 94:644df37bb05b 148 */
Christopher Haster 94:644df37bb05b 149 operator bool() const;
Christopher Haster 89:b1d417383c0d 150
Christopher Haster 89:b1d417383c0d 151 private:
Christopher Haster 89:b1d417383c0d 152 char _ip_address[NSAPI_IP_SIZE];
Christopher Haster 94:644df37bb05b 153 uint8_t _ip_bytes[NSAPI_IP_BYTES];
Christopher Haster 94:644df37bb05b 154 nsapi_version_t _ip_version;
Christopher Haster 89:b1d417383c0d 155 uint16_t _port;
Christopher Haster 89:b1d417383c0d 156 };
Christopher Haster 89:b1d417383c0d 157
Christopher Haster 89:b1d417383c0d 158 #endif