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


TCPSocket class hierarchy

The TCPSocket class provides the ability to send a stream of data over TCP. TCPSockets maintain a stateful connection that starts with the connect member function. After successfully connecting to a server, you can use the send and recv member functions to send and receive data (similar to writing or reading from a file).

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

Server socket

You can also use TCP to listen to incoming connections. To do this:

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

Accepting a new connection returns a pointer to a new Socket object that you can use to communicate with the connected peer. Afterward, call this socket's close() function to shut down the connection and clean up the reserved resources.

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

TCPSocket class reference

Public Member Functions
 TCPSocket ()
 Create an uninitialized socket. More...
int join_multicast_group (const SocketAddress &address)
 Override multicast functions to return error for TCP. More...
nsapi_error_t connect (const SocketAddress &address) override
 Connects TCP socket to a remote host. More...
nsapi_size_or_error_t send (const void *data, nsapi_size_t size) override
 Send data over a TCP socket. More...
nsapi_size_or_error_t recv (void *data, nsapi_size_t size) override
 Receive data over a TCP socket. More...
nsapi_size_or_error_t sendto (const SocketAddress &address, const void *data, nsapi_size_t size) override
 Send data on a socket. More...
nsapi_size_or_error_t recvfrom (SocketAddress *address, void *data, nsapi_size_t size) override
 Receive a data from a socket. 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 data on a packet with ancillary datasocket. 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 packet with ancillary data from a socket. More...
TCPSocketaccept (nsapi_error_t *error=NULL) override
 Accepts a connection on a socket. More...
nsapi_error_t listen (int backlog=1) override
 Listen for incoming connections. 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 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...

TCPSocket example

Here is a client example of HTTP transaction over TCPSocket:

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

// Network interface
EthernetInterface net;

// Socket demo
int main()
    // Bring up the ethernet interface
    printf("Ethernet socket example\n");

    // Show the network address
    SocketAddress a;
    printf("IP address: %s\n", a.get_ip_address() ? a.get_ip_address() : "None");

    // Open a socket on the network interface, and create a TCP connection to mbed.org
    TCPSocket socket;

    net.gethostbyname("ifconfig.io", &a);
    // Send a simple http request
    char sbuffer[] = "GET / HTTP/1.1\r\nHost: ifconfig.io\r\n\r\n";
    int scount = socket.send(sbuffer, sizeof sbuffer);
    printf("sent %d [%.*s]\n", scount, strstr(sbuffer, "\r\n") - sbuffer, sbuffer);

    // Recieve a simple http response and print out the response line
    char rbuffer[64];
    int rcount = socket.recv(rbuffer, sizeof rbuffer);
    printf("recv %d [%.*s]\n", rcount, strstr(rbuffer, "\r\n") - rbuffer, rbuffer);

    // Close the socket to return its memory and bring down the network interface

    // Bring down the ethernet interface

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.