Ethernet
EthInterface class hierarchy
The EthInterface
provides a C++ API for connecting to the internet over Ethernet. By default, this class does not require any configuration. It is able to pick up the default Ethernet driver for the target and select correct network stack.
Usage
To statically initialize the driver, create an object without passing any parameters:
EthernetInterface eth;
Then, if the default configuration is enough, bring up the interface:
nsapi_error_t status = eth.connect();
Now, the interface is ready to be used for network sockets.
// Open a TCP socket
TCPSocket socket;
socket.open(ð);
// Open a UDP socket
UDPSocket socket;
socket.open(ð);
Configuration
For EthernetInterface, there are two possible configurations:
- Use DHCP for network addressing. This is the default.
- Use statically configured IP addresses.
Refer to the API below for how to set the IP addresses by calling the set_network()
function.
Troubleshooting information
Network interface connect
failure causes:
NSAPI_ERROR_NO_CONNECTION
indicates that the Ethernet link up has failed. Check that the Ethernet connection is working.NSAPI_ERROR_DHCP_FAILURE
indicates that acquiring the IP address has failed. Check that the IP address configuration service is working.
EthInterface class reference
Public Types | |
typedef mbed::Callback< void(nsapi_value_or_error_t result, SocketAddress *address)> | hostbyname_cb_t |
Hostname translation callback (for use with gethostbyname_async()). More... |
Public Member Functions | |
EthInterface * | ethInterface () final |
Return pointer to an EthInterface. More... | |
virtual void | set_as_default () |
Set network interface as default one. More... | |
virtual const char * | get_mac_address () |
Get the local MAC address. More... | |
virtual nsapi_error_t | set_mac_address (uint8_t *mac_addr, nsapi_size_t addr_len) |
Set the MAC address to the interface. More... | |
virtual nsapi_error_t | get_ip_address (SocketAddress *address) |
Get the local IP address. More... | |
virtual nsapi_error_t | get_ipv6_link_local_address (SocketAddress *address) |
Get the IPv6 link local address. More... | |
virtual nsapi_error_t | get_netmask (SocketAddress *address) |
Get the local network mask. More... | |
virtual nsapi_error_t | get_gateway (SocketAddress *address) |
Get the local gateway. More... | |
virtual char * | get_interface_name (char *interface_name) |
Get the network interface name. More... | |
virtual nsapi_error_t | set_network (const SocketAddress &ip_address, const SocketAddress &netmask, const SocketAddress &gateway) |
Configure this network interface to use a static IP address. More... | |
virtual nsapi_error_t | set_dhcp (bool dhcp) |
Enable or disable DHCP on connecting the network. More... | |
virtual nsapi_error_t | connect ()=0 |
Connect to a network. More... | |
virtual nsapi_error_t | disconnect ()=0 |
Disconnect from the network. More... | |
virtual nsapi_error_t | gethostbyname (const char *host, SocketAddress *address, nsapi_version_t version=NSAPI_UNSPEC, const char *interface_name=NULL) |
Translate a hostname to an IP address with specific version using network interface name. More... | |
virtual nsapi_value_or_error_t | getaddrinfo (const char *hostname, SocketAddress *hints, SocketAddress **res, const char *interface_name=NULL) |
Translate a hostname to the multiple IP addresses with specific version using network interface name. More... | |
virtual nsapi_value_or_error_t | gethostbyname_async (const char *host, hostbyname_cb_t callback, nsapi_version_t version=NSAPI_UNSPEC, const char *interface_name=NULL) |
Translate a hostname to an IP address (asynchronous) using network interface name. More... | |
virtual nsapi_value_or_error_t | getaddrinfo_async (const char *hostname, SocketAddress *hints, hostbyname_cb_t callback, const char *interface_name=NULL) |
Translate a hostname to the multiple IP addresses (asynchronous) using network interface name. More... | |
virtual nsapi_error_t | gethostbyname_async_cancel (int id) |
Cancel asynchronous hostname translation. More... | |
virtual nsapi_error_t | add_dns_server (const SocketAddress &address, const char *interface_name) |
Add a domain name server to list of servers to query. More... | |
virtual nsapi_error_t | get_dns_server (int index, SocketAddress *address, const char *interface_name=NULL) |
Get a domain name server from a list of servers to query. More... | |
virtual void | attach (mbed::Callback< void(nsapi_event_t, intptr_t)> status_cb) |
Register callback for status reporting. More... | |
void | add_event_listener (mbed::Callback< void(nsapi_event_t, intptr_t)> status_cb) |
Add event listener for interface. More... | |
virtual nsapi_connection_status_t | get_connection_status () const |
Get the connection status. More... | |
virtual nsapi_error_t | set_blocking (bool blocking) |
Set asynchronous operation of connect() and disconnect() calls. More... | |
virtual WiFiInterface * | wifiInterface () |
Return pointer to a WiFiInterface. More... | |
virtual MeshInterface * | meshInterface () |
Return pointer to a MeshInterface. More... | |
virtual EMACInterface * | emacInterface () |
Return pointer to an EMACInterface. More... | |
virtual CellularInterface * | cellularInterface () |
Return pointer to a CellularInterface. More... | |
virtual void | set_default_parameters () |
defined(DOXYGEN_ONLY) More... |
Static Public Member Functions | |
static EthInterface * | get_default_instance () |
Get the default Ethernet interface. More... |
EthInterface example
Here is an example of an HTTP client program. The program brings up Ethernet as the underlying network interface and uses it to perform an HTTP transaction over a 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");
net.connect();
// Show the network address
SocketAddress a;
net.get_ip_address(&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;
socket.open(&net);
net.gethostbyname("ifconfig.io", &a);
a.set_port(80);
socket.connect(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
socket.close();
// Bring down the ethernet interface
net.disconnect();
printf("Done\n");
}
Related content
- Network socket API reference overview.
- Ethernet architecture.