Zephyr API Documentation 4.5.99
A Scalable Open Source RTOS
Loading...
Searching...
No Matches

STUN client. More...

Files

file  stun_client.h
 STUN client over UDP sockets.

Macros

#define STUN_CLIENT_DEFAULT_PORT   3478U
 Port STUN servers listen on by default (RFC 8489, section-18.6).

Functions

int stun_client_query (int sock, const struct net_sockaddr *server, net_socklen_t server_len, uint32_t timeout_ms, struct net_sockaddr_storage *mapped)
 Ask a STUN server for the address it sees a socket at.
int stun_client_simple (const char *host, uint16_t port, uint32_t timeout_ms, struct net_sockaddr_storage *mapped)
 Ask a STUN server, given by name, for the address it sees this device at.

Detailed Description

STUN client.

Since
4.6
Version
0.1.0

Asks a STUN server which transport address it sees this device at: the address on the outside of the NAT, if there is one. Built on the Binding transaction of STUN (Session Traversal Utilities for NAT), with the sockets, the clock and the random number generator that the transaction leaves to its caller.

A protocol that shares its socket with STUN, as ICE does, uses the transaction directly instead: the calls here block and consume everything that arrives on the socket in the meantime.

Macro Definition Documentation

◆ STUN_CLIENT_DEFAULT_PORT

#define STUN_CLIENT_DEFAULT_PORT   3478U

#include <zephyr/net/stun_client.h>

Port STUN servers listen on by default (RFC 8489, section-18.6).

Function Documentation

◆ stun_client_query()

int stun_client_query ( int sock,
const struct net_sockaddr * server,
net_socklen_t server_len,
uint32_t timeout_ms,
struct net_sockaddr_storage * mapped )

#include <zephyr/net/stun_client.h>

Ask a STUN server for the address it sees a socket at.

Sends a Binding request from sock and waits for the answer, retransmitting as RFC 8489, section-6.2.1 has it. The address returned is that of sock as the server sees it, so it is the one to tell a peer that is to reach this very socket.

The call blocks. For its duration the socket is the transaction's alone: datagrams that are not the server's answer are received and dropped.

Parameters
sockUDP socket, of the family of server.
serverAddress and port of the STUN server.
server_lenSize of server.
timeout_msLongest time to wait, in milliseconds; 0 to wait for as long as the retransmission schedule lasts: 39.5 seconds, more if the calling thread is held up between the transmissions.
[out]mappedReceives the address and port the server saw. The address can be of a family other than that of server.
Return values
0Success.
-ETIMEDOUTNo answer in time.
-EPROTOThe server answered with an error, or with a response that cannot be used.
-EINVALNULL argument, server_len too short for the address, or a server without a port or with the unspecified address.
-EAFNOSUPPORTThe server address is neither IPv4 nor IPv6, or it is IPv6 and the IPv6 stack is not enabled.
-EIONo random transaction id could be generated, or the socket reported an event that is neither data nor an error it can name.
Returns
Another negative errno if sending or receiving failed, or the error the socket reported, such as -ECONNREFUSED.

◆ stun_client_simple()

int stun_client_simple ( const char * host,
uint16_t port,
uint32_t timeout_ms,
struct net_sockaddr_storage * mapped )

#include <zephyr/net/stun_client.h>

Ask a STUN server, given by name, for the address it sees this device at.

Resolves the name and asks the addresses it resolves to one after another, until one of them answers. A time given is shared between the addresses: each gets an equal part of what is left of it. For each address it opens a UDP socket of the family of the address, connects it to that address, so that the socket receives only the datagrams of the server, calls stun_client_query() and closes the socket. The address returned tells the public IP address of the device; the port belonged to the socket that is gone by the time the call returns.

Parameters
hostHost name or literal address of the server: "stun.example.org", "192.0.2.1", "2001:db8::1".
portPort of the server; 0 for STUN_CLIENT_DEFAULT_PORT.
timeout_msLongest time to wait for an answer, in milliseconds, all addresses taken together; 0 to wait at each address for as long as the retransmission schedule lasts, see stun_client_query(). Resolving the name is not counted.
[out]mappedReceives the address and port the server saw. The address can be of a family other than that of the server.
Return values
0Success.
-EHOSTUNREACHThe name could not be resolved. A host name, as opposed to a literal address, takes CONFIG_DNS_RESOLVER.
Returns
Otherwise as stun_client_query(), or a negative errno if no socket could be opened or connected. If no address answered, the error is that of the last one tried.