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 and recvfrom 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...
template<typename S >
 UDPSocket (S *stack)
 Create and open a socket on the network stack of the given network interface. More...
virtual nsapi_size_or_error_t sendto (const char *host, uint16_t port, const void *data, nsapi_size_t size)
 Send data to the specified host and port. More...
virtual nsapi_size_or_error_t sendto (const SocketAddress &address, const void *data, nsapi_size_t size)
 Send data to the specified address. More...
virtual nsapi_size_or_error_t recvfrom (SocketAddress *address, void *data, nsapi_size_t size)
 Receive a datagram and store the source address in address if it's not NULL. More...
virtual nsapi_error_t connect (const SocketAddress &address)
 Set the remote address for next send() call and filtering of incoming packets. More...
virtual nsapi_size_or_error_t send (const void *data, nsapi_size_t size)
 Send a raw data to connected remote address. More...
virtual nsapi_size_or_error_t recv (void *data, nsapi_size_t size)
 Receive data from a socket. More...
virtual Socketaccept (nsapi_error_t *error=NULL)
 Not implemented for InternetDatagramSocket. More...
virtual nsapi_error_t listen (int backlog=1)
 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...
virtual nsapi_error_t close ()
 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 char *address, uint16_t port)
 Bind the socket to a specific address and port on which to receive data. More...
virtual nsapi_error_t bind (const SocketAddress &address)
 Bind a specific address to a socket. More...
virtual void set_blocking (bool blocking)
 Set blocking or non-blocking mode of the socket. More...
virtual void set_timeout (int timeout)
 Set timeout on blocking socket operations. More...
virtual nsapi_error_t setsockopt (int level, int optname, const void *optval, unsigned optlen)
 Set socket options. More...
virtual nsapi_error_t getsockopt (int level, int optname, void *optval, unsigned *optlen)
 Get socket options. More...
virtual void sigio (mbed::Callback< void()> func)
 Register a callback on state change of the socket. More...
virtual nsapi_error_t getpeername (SocketAddress *address)
 Get the remote-end peer associated with this socket. More...
void attach (mbed::Callback< void()> func)
 Register a callback on state change of the socket. More...
template<typename T , typename M >
void attach (T *obj, M method)
 Register a callback on state change of the socket. More...

UDPSocket example

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

#include "mbed.h"
#include "EthernetInterface.h"
// Network interface
EthernetInterface net;
// Time protocol implementation : Address: time.nist.gov UDPPort: 37  
typedef struct {
    uint32_t secs;         // Transmit Time-stamp seconds.
int main() {
    // Bring up the ethernet interface
    printf("UDP Socket example\n");
    if(0 != net.connect()) {
        printf("Error connecting\n");
        return -1;
    // Show the network address
    const char *ip = net.get_ip_address();
    printf("IP address is: %s\n", ip ? ip : "No IP");
    UDPSocket sock(&net);
    SocketAddress sockAddr;
    char out_buffer[] = "time";
    if(0 > sock.sendto("time.nist.gov", 37, out_buffer, sizeof(out_buffer))) {
        printf("Error sending data\n");
        return -1;
    ntp_packet in_data;
    int n = 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.