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.

Committer:
Christopher Haster
Date:
Thu Feb 18 04:09:00 2016 -0600
Branch:
api-changes
Revision:
24:a5e959bdd2dd
Parent:
21:35ed15069189
Child:
25:ed7b2a52e8ac
Added setURL for DNS lookups

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Christopher Haster 21:35ed15069189 1 /* TCPSocket
Christopher Haster 21:35ed15069189 2 * Copyright (c) 2015 ARM Limited
Christopher Haster 21:35ed15069189 3 *
Christopher Haster 21:35ed15069189 4 * Licensed under the Apache License, Version 2.0 (the "License");
Christopher Haster 21:35ed15069189 5 * you may not use this file except in compliance with the License.
Christopher Haster 21:35ed15069189 6 * You may obtain a copy of the License at
Christopher Haster 21:35ed15069189 7 *
Christopher Haster 21:35ed15069189 8 * http://www.apache.org/licenses/LICENSE-2.0
Christopher Haster 21:35ed15069189 9 *
Christopher Haster 21:35ed15069189 10 * Unless required by applicable law or agreed to in writing, software
Christopher Haster 21:35ed15069189 11 * distributed under the License is distributed on an "AS IS" BASIS,
Christopher Haster 21:35ed15069189 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
Christopher Haster 21:35ed15069189 13 * See the License for the specific language governing permissions and
Christopher Haster 21:35ed15069189 14 * limitations under the License.
Christopher Haster 21:35ed15069189 15 */
Christopher Haster 21:35ed15069189 16
Christopher Haster 21:35ed15069189 17 #ifndef TCP_SOCKET_H
Christopher Haster 21:35ed15069189 18 #define TCP_SOCKET_H
Christopher Haster 21:35ed15069189 19
Christopher Haster 21:35ed15069189 20 #include "NetworkInterface.h"
Christopher Haster 21:35ed15069189 21
Christopher Haster 21:35ed15069189 22 /** TCPSocket class
Christopher Haster 21:35ed15069189 23 * API for handling TCP sockets. The implementation is determined
Christopher Haster 21:35ed15069189 24 * by the interface passed during construction.
Christopher Haster 21:35ed15069189 25 */
Christopher Haster 21:35ed15069189 26 class TCPSocket
Christopher Haster 21:35ed15069189 27 {
Christopher Haster 21:35ed15069189 28 public:
Christopher Haster 21:35ed15069189 29 /** Create a socket using the specified network interface
Christopher Haster 21:35ed15069189 30 * @param iface The network interface to use
Christopher Haster 24:a5e959bdd2dd 31 * @param ip Optional URL to connect to, copied internally
Christopher Haster 21:35ed15069189 32 * @param port Optional port to connect to
Christopher Haster 21:35ed15069189 33 */
Christopher Haster 24:a5e959bdd2dd 34 TCPSocket(NetworkInterface *iface, const char *url = 0, uint16_t port = 0);
Christopher Haster 21:35ed15069189 35
Christopher Haster 21:35ed15069189 36 /** Closes and destroys the socket
Christopher Haster 21:35ed15069189 37 */
Christopher Haster 21:35ed15069189 38 ~TCPSocket();
Christopher Haster 21:35ed15069189 39
Christopher Haster 21:35ed15069189 40
Christopher Haster 24:a5e959bdd2dd 41 /** Set the URL of the socket
Christopher Haster 24:a5e959bdd2dd 42 * Performs DNS lookup if necessary
Christopher Haster 24:a5e959bdd2dd 43 * @param url URL to connect to
Christopher Haster 24:a5e959bdd2dd 44 */
Christopher Haster 24:a5e959bdd2dd 45 void setURL(const char *url);
Christopher Haster 24:a5e959bdd2dd 46
Christopher Haster 21:35ed15069189 47 /** Set the IP address of the socket
Christopher Haster 21:35ed15069189 48 * @param ip IP address to connect to, copied internally
Christopher Haster 21:35ed15069189 49 */
Christopher Haster 21:35ed15069189 50 void setIPAddress(const char *ip);
Christopher Haster 21:35ed15069189 51
Christopher Haster 21:35ed15069189 52 /** Set the port of the socket
Christopher Haster 21:35ed15069189 53 * @param port Port to connect to
Christopher Haster 21:35ed15069189 54 */
Christopher Haster 21:35ed15069189 55 void setPort(uint16_t port);
Christopher Haster 21:35ed15069189 56
Christopher Haster 21:35ed15069189 57 /** Gets the IP address
Christopher Haster 21:35ed15069189 58 * @return IP address to connect to
Christopher Haster 21:35ed15069189 59 */
Christopher Haster 21:35ed15069189 60 const char *getIPAddress();
Christopher Haster 21:35ed15069189 61
Christopher Haster 21:35ed15069189 62 /** Gets the port
Christopher Haster 21:35ed15069189 63 * @return Port to connect to
Christopher Haster 21:35ed15069189 64 */
Christopher Haster 21:35ed15069189 65 uint16_t getPort();
Christopher Haster 21:35ed15069189 66
Christopher Haster 21:35ed15069189 67
Christopher Haster 21:35ed15069189 68 /** Open a connection to the underlying address
Christopher Haster 21:35ed15069189 69 * @return 0 on success
Christopher Haster 21:35ed15069189 70 */
Christopher Haster 21:35ed15069189 71 int32_t open();
Christopher Haster 21:35ed15069189 72
Christopher Haster 21:35ed15069189 73 /** Close an open connection
Christopher Haster 21:35ed15069189 74 * @return 0 on success
Christopher Haster 21:35ed15069189 75 */
Christopher Haster 21:35ed15069189 76 int32_t close();
Christopher Haster 21:35ed15069189 77
Christopher Haster 21:35ed15069189 78 /** Send data over TCP
Christopher Haster 21:35ed15069189 79 * @param data Buffer of data to send
Christopher Haster 21:35ed15069189 80 * @param len Size of data to send
Christopher Haster 21:35ed15069189 81 * @param timeout_ms Maximum amount of time to wait
Christopher Haster 21:35ed15069189 82 * @return 0 on success
Christopher Haster 21:35ed15069189 83 */
Christopher Haster 21:35ed15069189 84 int32_t send(const void *data, uint32_t len, uint32_t timeout_ms = 15000);
Christopher Haster 21:35ed15069189 85
Christopher Haster 21:35ed15069189 86 /** Recieve data over TCP
Christopher Haster 21:35ed15069189 87 * @param data Buffer to store recieved data
Christopher Haster 21:35ed15069189 88 * @param len Size of provided buffer
Christopher Haster 21:35ed15069189 89 * @param timeout_ms Maximum amount of time to wait
Christopher Haster 21:35ed15069189 90 * @return Number of bytes sent or a negative value on failure
Christopher Haster 21:35ed15069189 91 */
Christopher Haster 21:35ed15069189 92 int32_t recv(void *data, uint32_t len, uint32_t timeout_ms = 15000);
Christopher Haster 21:35ed15069189 93
Christopher Haster 21:35ed15069189 94 private:
Christopher Haster 21:35ed15069189 95 NetworkInterface *_iface;
Christopher Haster 21:35ed15069189 96 SocketInterface *_socket;
Christopher Haster 21:35ed15069189 97 };
Christopher Haster 21:35ed15069189 98
Christopher Haster 21:35ed15069189 99 #endif