Mistake on this page?
Report an issue in GitHub or email us


Socket class hierarchy

Socket is the abstract base class for all of the protocol-specific socket types. It defines all of the functions that comprise the Mbed OS Socket API. You cannot directly create a Socket object because it is abstract, but you can upcast any protocol-specific object to an abstract Socket object.

You can use this interface when designing portable application interfaces that do not require specific protocol to be defined. For example, instead of using TCPSocket* in methods, the application can use Socket* to allow either UDP or TCP to work, or even TLS.

The Socket class defines the Mbed OS Socket API and loosely follows the POSIX standard (IEEE Std 1003.1). The following table lists the methods from the Socket API and their relevant POSIX standards:

Method Description POSIX standard
Socket::connect() Connect socket to a remote address connect
Socket::close Closes any open connection and deallocates any memory associated with the socket close
Socket::send() Send data over a socket send
Socket::recv() Receive data from a socket recv
Socket::sendto() Sends data to the specified address. sendto
Socket::recvfrom() Receives data and stores the source address recvfrom
Socket::sendto_control() Similar to sendto but support message control through ancilary data. sendto, sendmsg
Socket::recvfrom_control() Similar to recvfrom but support message control through ancilary data. recvfrom, sendmsg
Socket::bind() Bind a specific address to a socket bind
Socket::listen() Listen for incoming connections listen
Socket::accept() Accept incoming connection accept
Socket::setsockopt() Set the socket options setsockopt
Socket::getsockopt() Get the socket options getsockopt

Not all protocols implement every function from the Socket API. For example, UDP does not implement the listen() and accept() functions. Also, socket options are mostly specific to the IP stack; they are not implemented on all stacks.

Socket class reference

Public Member Functions
virtual ~Socket ()=default
 Destroy a socket. More...
virtual nsapi_error_t close ()=0
 Closes the socket. More...
virtual nsapi_error_t connect (const SocketAddress &address)=0
 Connects socket to a remote address. More...
virtual nsapi_size_or_error_t send (const void *data, nsapi_size_t size)=0
 Send data on a socket. More...
virtual nsapi_size_or_error_t recv (void *data, nsapi_size_t size)=0
 Receive data from a socket. More...
virtual nsapi_size_or_error_t sendto (const SocketAddress &address, const void *data, nsapi_size_t size)=0
 Send a message on a socket. More...
virtual nsapi_size_or_error_t recvfrom (SocketAddress *address, void *data, nsapi_size_t size)=0
 Receive a data from a socket. More...
virtual nsapi_size_or_error_t sendto_control (const SocketAddress &address, const void *data, nsapi_size_t size, nsapi_msghdr_t *control, nsapi_size_t control_size)=0
 Send a message on a socket. More...
virtual nsapi_size_or_error_t recvfrom_control (SocketAddress *address, void *data, nsapi_size_t size, nsapi_msghdr_t *control, nsapi_size_t control_size)=0
 Receive a data from a socket. More...
virtual nsapi_error_t bind (const SocketAddress &address)=0
 Bind a specific address to a socket. More...
virtual void set_blocking (bool blocking)=0
 Set blocking or non-blocking mode of the socket. More...
virtual void set_timeout (int timeout)=0
 Set timeout on blocking socket operations. More...
virtual void sigio (mbed::Callback< void()> func)=0
 Register a callback on state change of the socket. More...
virtual nsapi_error_t setsockopt (int level, int optname, const void *optval, unsigned optlen)=0
 Set socket options. More...
virtual nsapi_error_t getsockopt (int level, int optname, void *optval, unsigned *optlen)=0
 Get socket options. More...
virtual Socketaccept (nsapi_error_t *error=NULL)=0
 Accepts a connection on a socket. More...
virtual nsapi_error_t listen (int backlog=1)=0
 Listen for incoming connections. More...
virtual nsapi_error_t getpeername (SocketAddress *address)=0
 Get the remote-end peer associated with this socket. More...

Socket example

Here is a client example of HTTP transaction over TCPSocket or TLSSocket:

/* Sockets Example
 * Copyright (c) 2016-2020 ARM Limited
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *     http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * See the License for the specific language governing permissions and
 * limitations under the License.

#include "mbed.h"
#include "wifi_helper.h"
#include "mbed-trace/mbed_trace.h"

#include "root_ca_cert.h"

#error "mbed-os-example-tls-socket requires a device which supports TRNG"

class SocketDemo {
    static constexpr size_t MAX_NUMBER_OF_ACCESS_POINTS = 10;
    static constexpr size_t MAX_MESSAGE_RECEIVED_LENGTH = 100;

    static constexpr size_t REMOTE_PORT = 443; // tls port
    static constexpr size_t REMOTE_PORT = 80; // standard HTTP port

    SocketDemo() : _net(NetworkInterface::get_default_instance())

        if (_net) {

    void run()
        if (!_net) {
            printf("Error! No network interface found.\r\n");

        /* if we're using a wifi interface run a quick scan */
        if (_net->wifiInterface()) {
            /* the scan is not required to connect and only serves to show visible access points */

            /* in this example we use credentials configured at compile time which are used by
             * NetworkInterface::connect() but it's possible to do this at runtime by using the
             * WiFiInterface::connect() which takes these parameters as arguments */

        /* connect will perform the action appropriate to the interface type to connect to the network */

        printf("Connecting to the network...\r\n");

        nsapi_size_or_error_t result = _net->connect();
        if (result != 0) {
            printf("Error! _net->connect() returned: %d\r\n", result);


        /* opening the socket only allocates resources */
        result = _socket.open(_net);
        if (result != 0) {
            printf("Error! _socket.open() returned: %d\r\n", result);

        result = _socket.set_root_ca_cert(root_ca_cert);
        if (result != NSAPI_ERROR_OK) {
            printf("Error: _socket.set_root_ca_cert() returned %d\n", result);

        /* now we have to find where to connect */

        SocketAddress address;

        if (!resolve_hostname(address)) {


        /* we are connected to the network but since we're using a connection oriented
         * protocol we still need to open a connection on the socket */

        printf("Opening connection to remote port %d\r\n", REMOTE_PORT);

        result = _socket.connect(address);
        if (result != 0) {
            printf("Error! _socket.connect() returned: %d\r\n", result);

        /* exchange an HTTP request and response */

        if (!send_http_request()) {

        if (!receive_http_response()) {

        printf("Demo concluded successfully \r\n");

    bool resolve_hostname(SocketAddress &address)
        const char hostname[] = MBED_CONF_APP_HOSTNAME;

        /* get the host address */
        printf("\nResolve hostname %s\r\n", hostname);
        nsapi_size_or_error_t result = _net->gethostbyname(hostname, &address);
        if (result != 0) {
            printf("Error! gethostbyname(%s) returned: %d\r\n", hostname, result);
            return false;

        printf("%s address is %s\r\n", hostname, (address.get_ip_address() ? address.get_ip_address() : "None") );

        return true;

    bool send_http_request()
        /* loop until whole request sent */
        const char buffer[] = "GET / HTTP/1.1\r\n"
                              "Host: ifconfig.io\r\n"
                              "Connection: close\r\n"

        nsapi_size_t bytes_to_send = strlen(buffer);
        nsapi_size_or_error_t bytes_sent = 0;

        printf("\r\nSending message: \r\n%s", buffer);

        while (bytes_to_send) {
            bytes_sent = _socket.send(buffer + bytes_sent, bytes_to_send);
            if (bytes_sent < 0) {
                printf("Error! _socket.send() returned: %d\r\n", bytes_sent);
                return false;
            } else {
                printf("sent %d bytes\r\n", bytes_sent);

            bytes_to_send -= bytes_sent;

        printf("Complete message sent\r\n");

        return true;

    bool receive_http_response()
        char buffer[MAX_MESSAGE_RECEIVED_LENGTH];
        int remaining_bytes = MAX_MESSAGE_RECEIVED_LENGTH;
        int received_bytes = 0;

        /* loop until there is nothing received or we've ran out of buffer space */
        nsapi_size_or_error_t result = remaining_bytes;
        while (result > 0 && remaining_bytes > 0) {
            result = _socket.recv(buffer + received_bytes, remaining_bytes);
            if (result < 0) {
                printf("Error! _socket.recv() returned: %d\r\n", result);
                return false;

            received_bytes += result;
            remaining_bytes -= result;

        /* the message is likely larger but we only want the HTTP response code */

        printf("received %d bytes:\r\n%.*s\r\n\r\n", received_bytes, strstr(buffer, "\n") - buffer, buffer);

        return true;

    void wifi_scan()
        WiFiInterface *wifi = _net->wifiInterface();

        WiFiAccessPoint ap[MAX_NUMBER_OF_ACCESS_POINTS];

        /* scan call returns number of access points found */
        int result = wifi->scan(ap, MAX_NUMBER_OF_ACCESS_POINTS);

        if (result <= 0) {
            printf("WiFiInterface::scan() failed with return value: %d\r\n", result);

        printf("%d networks available:\r\n", result);

        for (int i = 0; i < result; i++) {
            printf("Network: %s secured: %s BSSID: %hhX:%hhX:%hhX:%hhx:%hhx:%hhx RSSI: %hhd Ch: %hhd\r\n",
                   ap[i].get_ssid(), get_security_string(ap[i].get_security()),
                   ap[i].get_bssid()[0], ap[i].get_bssid()[1], ap[i].get_bssid()[2],
                   ap[i].get_bssid()[3], ap[i].get_bssid()[4], ap[i].get_bssid()[5],
                   ap[i].get_rssi(), ap[i].get_channel());

    void print_network_info()
        /* print the network info */
        SocketAddress a;
        printf("IP address: %s\r\n", a.get_ip_address() ? a.get_ip_address() : "None");
        printf("Netmask: %s\r\n", a.get_ip_address() ? a.get_ip_address() : "None");
        printf("Gateway: %s\r\n", a.get_ip_address() ? a.get_ip_address() : "None");

    NetworkInterface *_net;

    TLSSocket _socket;
    TCPSocket _socket;

int main() {
    printf("\r\nStarting socket demo\r\n\r\n");


    SocketDemo *example = new SocketDemo();

    return 0;

Important Information for this Arm website

This site uses cookies to store information on your computer. By continuing to use our site, you consent to our cookies. If you are not happy with the use of these cookies, please review our Cookie Policy to learn how they can be disabled. By disabling cookies, some features of the site will not work.