Network socket

The application programming interface for IP networking is the Socket API. As described in the IP networking section, the Socket API relates to OSI layer 4, the Transport layer. In Mbed OS, the Socket API is abstract and supports various protocols such as TCP, UDP and non-IP data delivery for NB-IoT cellular networks.

Sockets

In Mbed OS, this socket API is C++ based but closely follows the functionality from the POSIX standard (IEEE Std 1003.1) and relevant RFC standards. The Socket interface is abstract and protocol agnostic and requires you to specify the protocol only when creating the socket. With libraries and interfaces, you may use the abstract base class, which allows you to port applications from one protocol to another.

General use

The following steps describe the typical application flow:

1. Initialize a network interface.
2. Create a socket.
3. Connect (optional step for datagram protocols).
4. Send data.
5. Receive data.
6. Close the socket.

The following code demonstrates those steps by sending an HTTP query to a server:

// Initialize network interface
EthernetInterface eth;
eth.connect();

// Create a socket
TCPSocket sock;
sock.open(&eth);

// Connect
sock.connect("arm.com", 80);

// Send data
sock.send("GET / HTTP/1.0\r\n\r\n", 18);

// Receive data
char buf[100];
sock.recv(buf, 100);

// Close the socket
sock.close();

Using DNS names

IP stacks operate only on binary IP addresses, but in Internet, servers are known by their symbolic domain name (DNS). To use these names with Socket interface, each name has to be resolved before.

Previously Socket interface contained methods that can directly accept DNS names and port numbers and do the resolving internally. These APIs are not recommended as they might hide problems in DNS system.

Recommended way is to use DNS resolver to convert symbolic names to IP addresses. The following example shows how to use DNS in Mbed OS:

NetworkInteface *net;    // Initialized elsewhere

SocketAddress addr;
nsapi_error_t ret = net->gethostbyname("www.arm.com", &addr);  // Resolve www.arm.com and store into addr

if (ret == NSAPI_ERROR_OK) {
    // Resolving was succesfull
}

See DNS resolver for more information.

Server sockets

Some connection oriented protocols, for example TCP, can also be used for listening incomming connections. To do this

1. Bind socket to specific port by calling Socket::bind()
2. Set socket to listening mode by calling Socket::listen()
3. Accept incomming connection by calling Socket::accept()

Accepting new connection return you a pointer to a new Socket object that can be used to communicate with the connected peer. When done, you should call this socket's close() function to shut down the connection and clean up the reserved resources.

Accepting a connection will leave the original socket to listening mode. You can continue to accept new connections until you destroy the listening socket, or call its close() method.

For connectionless protocols, like UDP, each socket can receive from any peer. Therefore listen() and accept() are not required.