Socket
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::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_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 Socket * | accept (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:
#include "mbed.h"
#include "mbed_trace.h"
#ifndef DEVICE_TRNG
#error "mbed-os-example-tls-socket requires a device which supports TRNG"
#else
const char cert[] = \
"-----BEGIN CERTIFICATE-----\n"
"MIIDdzCCAl+gAwIBAgIEAgAAuTANBgkqhkiG9w0BAQUFADBaMQswCQYDVQQGEwJJ\n"
"RTESMBAGA1UEChMJQmFsdGltb3JlMRMwEQYDVQQLEwpDeWJlclRydXN0MSIwIAYD\n"
"VQQDExlCYWx0aW1vcmUgQ3liZXJUcnVzdCBSb290MB4XDTAwMDUxMjE4NDYwMFoX\n"
"DTI1MDUxMjIzNTkwMFowWjELMAkGA1UEBhMCSUUxEjAQBgNVBAoTCUJhbHRpbW9y\n"
"ZTETMBEGA1UECxMKQ3liZXJUcnVzdDEiMCAGA1UEAxMZQmFsdGltb3JlIEN5YmVy\n"
"VHJ1c3QgUm9vdDCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBAKMEuyKr\n"
"mD1X6CZymrV51Cni4eiVgLGw41uOKymaZN+hXe2wCQVt2yguzmKiYv60iNoS6zjr\n"
"IZ3AQSsBUnuId9Mcj8e6uYi1agnnc+gRQKfRzMpijS3ljwumUNKoUMMo6vWrJYeK\n"
"mpYcqWe4PwzV9/lSEy/CG9VwcPCPwBLKBsua4dnKM3p31vjsufFoREJIE9LAwqSu\n"
"XmD+tqYF/LTdB1kC1FkYmGP1pWPgkAx9XbIGevOF6uvUA65ehD5f/xXtabz5OTZy\n"
"dc93Uk3zyZAsuT3lySNTPx8kmCFcB5kpvcY67Oduhjprl3RjM71oGDHweI12v/ye\n"
"jl0qhqdNkNwnGjkCAwEAAaNFMEMwHQYDVR0OBBYEFOWdWTCCR1jMrPoIVDaGezq1\n"
"BE3wMBIGA1UdEwEB/wQIMAYBAf8CAQMwDgYDVR0PAQH/BAQDAgEGMA0GCSqGSIb3\n"
"DQEBBQUAA4IBAQCFDF2O5G9RaEIFoN27TyclhAO992T9Ldcw46QQF+vaKSm2eT92\n"
"9hkTI7gQCvlYpNRhcL0EYWoSihfVCr3FvDB81ukMJY2GQE/szKN+OMY3EU/t3Wgx\n"
"jkzSswF07r51XgdIGn9w/xZchMB5hbgF/X++ZRGjD8ACtPhSNzkE1akxehi/oCr0\n"
"Epn3o0WC4zxe9Z2etciefC7IpJ5OCBRLbf1wbWsaY71k5h+3zvDyny67G7fyUIhz\n"
"ksLi4xaNmjICq44Y3ekQEe5+NauQrz4wlHrQMz2nZQ/1/I6eYs9HRCwBXbsdtTLS\n"
"R9I4LtD+gdwyah617jzV/OeBHRnDJELqYzmp\n"
"-----END CERTIFICATE-----";
int main(void)
{
char *buffer = new char[256];
nsapi_size_or_error_t result;
nsapi_size_t size;
const char query[] = "GET / HTTP/1.1\r\nHost: ifconfig.io\r\nConnection: close\r\n\r\n";
mbed_trace_init();
printf("TLSSocket Example.\n");
printf("Mbed OS version: %d.%d.%d\n\n", MBED_MAJOR_VERSION, MBED_MINOR_VERSION, MBED_PATCH_VERSION);
NetworkInterface *net = NetworkInterface::get_default_instance();
if (!net) {
printf("Error! No network inteface found.\n");
return 0;
}
printf("Connecting to network\n");
result = net->connect();
if (result != NSAPI_ERROR_OK) {
printf("Error! net->connect() returned: %d\n", result);
return result;
}
printf("Connecting to ifconfig.io\n");
SocketAddress addr;
result = net->gethostbyname("ifconfig.io", &addr);
if (result != NSAPI_ERROR_OK) {
printf("Error! DNS resolution for ifconfig.io failed with %d\n", result);
}
addr.set_port(443);
TLSSocket *socket = new TLSSocket;
result = socket->open(net);
if (result != NSAPI_ERROR_OK) {
printf("Error! socket->open() returned: %d\n", result);
return result;
}
socket->set_hostname("ifconfig.io");
result = socket->set_root_ca_cert(cert);
if (result != NSAPI_ERROR_OK) {
printf("Error: socket->set_root_ca_cert() returned %d\n", result);
return result;
}
result = socket->connect(addr);
if (result != NSAPI_ERROR_OK) {
printf("Error! socket->connect() returned: %d\n", result);
goto DISCONNECT;
}
// Send a simple http request
size = strlen(query);
result = socket->send(query, size);
if (result != size) {
printf("Error! socket->send() returned: %d\n", result);
goto DISCONNECT;
}
// Receieve an HTTP response and print out the response line
while ((result = socket->recv(buffer, 255)) > 0) {
buffer[result] = 0;
printf("%s", buffer);
}
printf("\n");
if (result < 0) {
printf("Error! socket->recv() returned: %d\n", result);
goto DISCONNECT;
}
DISCONNECT:
delete[] buffer;
// Close the socket to return its memory
socket->close();
delete socket;
// Bring down the network interface
net->disconnect();
printf("Done\n");
}
#endif