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.

Usage¶

#include "LWIPInterface.h"
#include "TCPSocket.h"

LWIPInterface lwip;
char buffer[1024];

int main() {
    TCPSocket sock(&lwip);
    
    lwip.connect();

    sock.open("www.mbed.org", 80);
    sock.send("GET / HTTP/1.1\r\n\r\n", 18);
    sock.recv(buffer, sizeof buffer);
    sock.close();

    lwip.disconnect();
}

Using the Network Socket API involves two core classes

• The Socket class for managing network sockets.
• A device provided DeviceInterface class that implements one of the NetworkInterface classes.

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.

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.

Errors¶

The convention for the NetworkSocketAPI is to have functions that may fail return a signed integer. To indicate succes, the function should return a non-negative integer which may also contain the size of a transaction. To indicate failure the function should return a negative integer which should be one of the following error codes:

• NS_ERROR_TIMEOUT
• NS_ERROR_NO_CONNECTION
• NS_ERROR_NO_SOCKET
• NS_ERROR_NO_ADDRESS
• NS_ERROR_NO_MEMORY
• NS_ERROR_DNS_FAILURE
• NS_ERROR_DHCP_FAILURE
• NS_ERROR_AUTH_FAILURE
• NS_ERROR_DEVICE_ERROR

Porting to new devices¶

The NetworkInterfaceAPI is designed to make porting new devices as easy as possible and only requires a handful of methods for a minimal implementation.

A new device must implement a NetworkInterface with the naming convention of DeviceInterface where Device is a unique name that represents the device. The DeviceInterface should inherit one of the following: EthernetInterface or WiFiInterface unless it is an abstract device. A DeviceInterface needs the following methods:

• connect - Interface specific connect function for bringing up the interface.
  • If getDHCP returns true, the interface should try to obtain an IP address. The network information can either be stored with the setIPAddress/setNetworkMask/setGateway methods or by directly overloading the getIPAddress/getNetworkMask/getGateway methods.
  • If getDHCP returns false, the interface should use the network information provided by the getIPAddress/getNetworkMask/getGateway methods or by directly overloading the setIPAddress/setNetworkMask/setGateway methods.
• disconnect - Interface specific disconnect function for bringing down the interface.
• getMACAddress - Access the MAC address of the interface.
• createSocket - Create a device-specific SocketInterface (outlined below) if possible. The protocol is provided as an argument to choose TCP sockets or UDP sockets.
• destroySocket - Destroy a socket created by createSocket.

Additionally, a new device must implement a SocketInterface that should be returned by calls to the createSocket methods of the NetworkInterface. If necessary, two different SocketInterfaces can be created for TCP and UDP sockets. The SocketInterface is managed by the user-facing Socket class. It is suggested to make this implementation private to the NetworkInterface to prevent users from accidentally creating a SocketInterface directly. A SocketInterface needs the following methods:

• open - Open the socket and connect to the provided IP address and port.
• close - Close an opened socket.
• send - Send data over the socket.
• recv - Receive data over the socket. If no data is currently available, this method should return immediately with a value of zero.