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::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 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 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,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* 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"
#if MBED_CONF_APP_USE_TLS_SOCKET
#include "root_ca_cert.h"
#ifndef DEVICE_TRNG
#error "mbed-os-example-tls-socket requires a device which supports TRNG"
#endif
#endif // MBED_CONF_APP_USE_TLS_SOCKET
class SocketDemo {
static constexpr size_t MAX_NUMBER_OF_ACCESS_POINTS = 10;
static constexpr size_t MAX_MESSAGE_RECEIVED_LENGTH = 100;
#if MBED_CONF_APP_USE_TLS_SOCKET
static constexpr size_t REMOTE_PORT = 443; // tls port
#else
static constexpr size_t REMOTE_PORT = 80; // standard HTTP port
#endif // MBED_CONF_APP_USE_TLS_SOCKET
public:
SocketDemo() : _net(NetworkInterface::get_default_instance())
{
}
~SocketDemo()
{
if (_net) {
_net->disconnect();
}
}
void run()
{
if (!_net) {
printf("Error! No network interface found.\r\n");
return;
}
/* 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 */
wifi_scan();
/* 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);
return;
}
print_network_info();
/* opening the socket only allocates resources */
result = _socket.open(_net);
if (result != 0) {
printf("Error! _socket.open() returned: %d\r\n", result);
return;
}
#if MBED_CONF_APP_USE_TLS_SOCKET
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);
return;
}
_socket.set_hostname(MBED_CONF_APP_HOSTNAME);
#endif // MBED_CONF_APP_USE_TLS_SOCKET
/* now we have to find where to connect */
SocketAddress address;
if (!resolve_hostname(address)) {
return;
}
address.set_port(REMOTE_PORT);
/* 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);
return;
}
/* exchange an HTTP request and response */
if (!send_http_request()) {
return;
}
if (!receive_http_response()) {
return;
}
printf("Demo concluded successfully \r\n");
}
private:
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"
"\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) {
nsapi_size_or_error_t 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);
return;
}
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());
}
printf("\r\n");
}
void print_network_info()
{
/* print the network info */
SocketAddress a;
_net->get_ip_address(&a);
printf("IP address: %s\r\n", a.get_ip_address() ? a.get_ip_address() : "None");
_net->get_netmask(&a);
printf("Netmask: %s\r\n", a.get_ip_address() ? a.get_ip_address() : "None");
_net->get_gateway(&a);
printf("Gateway: %s\r\n", a.get_ip_address() ? a.get_ip_address() : "None");
}
private:
NetworkInterface *_net;
#if MBED_CONF_APP_USE_TLS_SOCKET
TLSSocket _socket;
#else
TCPSocket _socket;
#endif // MBED_CONF_APP_USE_TLS_SOCKET
};
int main() {
printf("\r\nStarting socket demo\r\n\r\n");
#ifdef MBED_CONF_MBED_TRACE_ENABLE
mbed_trace_init();
#endif
SocketDemo *example = new SocketDemo();
MBED_ASSERT(example);
example->run();
return 0;
}