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


UDPSocket class hierarchy

The UDPSocket class provides the ability to send packets of data over UDP, using the sendto/sendto_control and recvfrom/recvfrom_control member functions. Packets can be lost or arrive out of order, so we suggest using a TCPSocket when you require guaranteed delivery.

The constructor takes no parameters. To initialize the socket on a specified NetworkInterface, you must call open method, which takes a NetworkStack pointer.

UDP is a connectionless protocol. This allows you to send and receive packets to and from any remote addresses. Therefore, Socket::listen() and Socket::accept() functions are not implemented on UDPSocket.

If you prefer to use send() and recv() functions and work only with one peer, UDPSocket does support the Socket::connect() function, which sets a permanent peer address to the socket. Setting the peer address starts filtering incoming packets, so they are accepted only from that specific address. You can reset the filtering and peer address by calling connect() with empty SocketAddress.

UDPSocket class reference

Public Member Functions
 UDPSocket ()
 Create an uninitialized socket. More...
nsapi_size_or_error_t sendto (const SocketAddress &address, const void *data, nsapi_size_t size) override
 Send data to the specified address. More...
nsapi_size_or_error_t recvfrom (SocketAddress *address, void *data, nsapi_size_t size) override
 Receive a datagram and store the source address in address if it's not NULL. More...
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) override
 Send datagram and ancillary data to the specified address. More...
nsapi_size_or_error_t recvfrom_control (SocketAddress *address, void *data, nsapi_size_t size, nsapi_msghdr_t *control, nsapi_size_t control_size) override
 Receive a datagram with ancillary data and store the source address in address if it's not NULL. More...
nsapi_error_t connect (const SocketAddress &address) override
 Set the remote address for next send() call and filtering of incoming packets. More...
nsapi_size_or_error_t send (const void *data, nsapi_size_t size) override
 Send a raw data to connected remote address. More...
nsapi_size_or_error_t recv (void *data, nsapi_size_t size) override
 Receive data from a socket. More...
Socketaccept (nsapi_error_t *error=nullptr) override
 Not implemented for InternetDatagramSocket. More...
nsapi_error_t listen (int backlog=1) override
 Not implemented for InternetDatagramSocket. More...
nsapi_error_t open (NetworkStack *stack)
 Open a network socket on the network stack of the given network interface. More...
nsapi_error_t close () override
 defined(DOXYGEN_ONLY) More...
int join_multicast_group (const SocketAddress &address)
 Subscribe to an IP multicast group. More...
int leave_multicast_group (const SocketAddress &address)
 Leave an IP multicast group. More...
int get_rtt_estimate_to_address (const SocketAddress &address, uint32_t *rtt_estimate)
 Get estimated round trip time to destination address. More...
int get_stagger_estimate_to_address (const SocketAddress &address, uint16_t data_amount, uint16_t *stagger_min, uint16_t *stagger_max, uint16_t *stagger_rand)
 Get estimated stagger value. More...
nsapi_error_t bind (uint16_t port)
 Bind the socket to a port on which to receive data. More...
nsapi_error_t bind (const SocketAddress &address) override
 Bind a specific address to a socket. More...
void set_blocking (bool blocking) override
 Set blocking or non-blocking mode of the socket. More...
void set_timeout (int timeout) override
 Set timeout on blocking socket operations. More...
nsapi_error_t setsockopt (int level, int optname, const void *optval, unsigned optlen) override
 Set socket options. More...
nsapi_error_t getsockopt (int level, int optname, void *optval, unsigned *optlen) override
 Get socket options. More...
void sigio (mbed::Callback< void()> func) override
 Register a callback on state change of the socket. More...
nsapi_error_t getpeername (SocketAddress *address) override
 Get the remote-end peer associated with this socket. More...

UDPSocket example

This UDP example reads the current UTC time by sending a request to the NIST Internet Time Service:

 * Copyright (c) 2006-2020 Arm Limited and affiliates.
 * SPDX-License-Identifier: Apache-2.0
#include "mbed.h"
#include "EthernetInterface.h"
#include "LWIPStack.h"

// Network interface
EthernetInterface net;

// Time protocol implementation : Address: time.nist.gov UDPPort: 37

typedef struct {
    uint32_t secs;         // Transmit Time-stamp seconds.
} ntp_packet;

int main()
    SocketAddress sockAddr;

    // Bring up the ethernet interface
    printf("UDP Socket example\n");
    if (0 != net.connect()) {
        printf("Error connecting\n");
        return -1;

    // Show the network address
    printf("IP address is: %s\n", sockAddr.get_ip_address() ? sockAddr.get_ip_address() : "No IP");

    UDPSocket sock;

    net.gethostbyname("time.nist.gov", &sockAddr);

    char out_buffer[] = "time";
    if (0 > sock.sendto(sockAddr, out_buffer, sizeof(out_buffer))) {
        printf("Error sending data\n");
        return -1;

    ntp_packet in_data;
    sock.recvfrom(&sockAddr, &in_data, sizeof(ntp_packet));
    in_data.secs = ntohl(in_data.secs) - 2208988800;      // 1900-1970
    printf("Time Received %lu seconds since 1/01/1900 00:00 GMT\n",
    printf("Time = %s", ctime((const time_t *)&in_data.secs));

    printf("Time Server Address: %s Port: %d\n\r",
           sockAddr.get_ip_address(), sockAddr.get_port());

    // Close the socket and bring down the network interface
    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.