RIOT's TCP implementation for the GNRC network stack. More...

Detailed Description

RIOT's TCP implementation for the GNRC network stack.

Topics
	GNRC TCP compile configurations

Files
file	tcp.h
	GNRC TCP API.

file	config.h
	GNRC TCP configuration.

file	tcb.h
	GNRC TCP transmission control block (TCB)

file	gnrc_tcp_common.h
	Internally used defines, macros and variable declarations.

file	gnrc_tcp_eventloop.h
	TCP event loop declarations.

file	gnrc_tcp_fsm.h
	TCP finite state machine declarations.

file	gnrc_tcp_option.h
	TCP option handling declarations.

file	gnrc_tcp_pkt.h
	TCP packet handling declarations.

file	gnrc_tcp_rcvbuf.h
	Functions for allocating and freeing the receive buffer.

Data Structures
struct	gnrc_tcp_ep_t
	Address information for a single TCP connection endpoint. More...

Macros
#define	GNRC_TCP_NO_TIMEOUT (UINT32_MAX)
	Special timeout value representing no timeout.

Functions
int	gnrc_tcp_ep_init (gnrc_tcp_ep_t ep, int family, const uint8_t addr, size_t addr_size, uint16_t port, uint16_t netif)
	Initialize TCP connection endpoint.

int	gnrc_tcp_ep_from_str (gnrc_tcp_ep_t ep, const char str)
	Construct TCP connection endpoint from string.

int	gnrc_tcp_init (void)
	Initialize TCP.

void	gnrc_tcp_tcb_init (gnrc_tcp_tcb_t *tcb)
	Initialize Transmission Control Block (TCB)

void	gnrc_tcp_tcb_queue_init (gnrc_tcp_tcb_queue_t *queue)
	Initialize Transmission Control Block (TCB) queue.

int	gnrc_tcp_open (gnrc_tcp_tcb_t tcb, const gnrc_tcp_ep_t remote, uint16_t local_port)
	Opens a connection.

int	gnrc_tcp_listen (gnrc_tcp_tcb_queue_t queue, gnrc_tcp_tcb_t tcbs, size_t tcbs_len, const gnrc_tcp_ep_t *local)
	Configures a sequence of TCBs to wait for incoming connections.

int	gnrc_tcp_accept (gnrc_tcp_tcb_queue_t queue, gnrc_tcp_tcb_t *tcb, const uint32_t user_timeout_duration_ms)
	Accept TCP connection from listening queue.

ssize_t	gnrc_tcp_send (gnrc_tcp_tcb_t tcb, const void data, const size_t len, const uint32_t user_timeout_duration_ms)
	Transmit data to connected peer.

ssize_t	gnrc_tcp_recv (gnrc_tcp_tcb_t tcb, void data, const size_t max_len, const uint32_t user_timeout_duration_ms)
	Receive Data from the peer.

void	gnrc_tcp_close (gnrc_tcp_tcb_t *tcb)
	Close a TCP connection.

void	gnrc_tcp_abort (gnrc_tcp_tcb_t *tcb)
	Abort a TCP connection.

void	gnrc_tcp_stop_listen (gnrc_tcp_tcb_queue_t *queue)
	Close connections and stop listening on TCB queue.

int	gnrc_tcp_get_local (gnrc_tcp_tcb_t tcb, gnrc_tcp_ep_t ep)
	Get the local end point of a connected TCB.

int	gnrc_tcp_get_remote (gnrc_tcp_tcb_t tcb, gnrc_tcp_ep_t ep)
	Get the remote end point of a connected TCB.

int	gnrc_tcp_queue_get_local (gnrc_tcp_tcb_queue_t queue, gnrc_tcp_ep_t ep)
	Gets the local end point of a TCB queue.

int	gnrc_tcp_calc_csum (const gnrc_pktsnip_t hdr, const gnrc_pktsnip_t pseudo_hdr)
	Calculate and set checksum in TCP header.

gnrc_pktsnip_t *	gnrc_tcp_hdr_build (gnrc_pktsnip_t *payload, uint16_t src, uint16_t dst)
	Adds a TCP header to a given payload.

Macro Definition Documentation

◆ GNRC_TCP_NO_TIMEOUT

#define GNRC_TCP_NO_TIMEOUT (UINT32_MAX)

Special timeout value representing no timeout.

Definition at line 47 of file tcp.h.

Function Documentation

◆ gnrc_tcp_abort()

void gnrc_tcp_abort ( gnrc_tcp_tcb_t * tcb )

Abort a TCP connection.

Precondition: gnrc_tcp_tcb_init() must have been successfully called.; tcb must not be NULL.

Parameters

[in,out] tcb TCB holding the connection information.

◆ gnrc_tcp_accept()

int gnrc_tcp_accept	(	gnrc_tcp_tcb_queue_t *	queue,
		gnrc_tcp_tcb_t **	tcb,
		const uint32_t	user_timeout_duration_ms )

Accept TCP connection from listening queue.

Precondition: queue must not be NULL; tcb must not be NULL

Note: Function blocks if user_timeout_duration_us is not zero.

Parameters

[in]	queue	Listening queue to accept connection from.
[out]	tcb	Pointer to TCB associated with a established connection.
[in]	user_timeout_duration_ms	User specified timeout in milliseconds. If GNRC_TCP_NO_TIMEOUT the function blocks until a connection was established or an error occurred.

Returns: 0 on success.; -ENOMEM if all connection in queue were already accepted.; -EINVAL if listen was never called on queue.; -EAGAIN if user_timeout_duration_ms was 0 and no connection is ready to accept.; -ETIMEDOUT if user_timeout_duration_ms was not 0 and no connection could be established.

◆ gnrc_tcp_calc_csum()

int gnrc_tcp_calc_csum	(	const gnrc_pktsnip_t *	hdr,
		const gnrc_pktsnip_t *	pseudo_hdr )

Calculate and set checksum in TCP header.

Parameters

[in]	hdr	Gnrc_pktsnip that contains TCP header.
[in]	pseudo_hdr	Gnrc_pktsnip that contains network layer header.

Returns: 0 on success.; -EFAULT if hdr or pseudo_hdr were NULL; -EBADMSG if hdr is not of type GNRC_NETTYPE_TCP; -ENOENT if pseudo_hdr protocol is unsupported.

◆ gnrc_tcp_close()

void gnrc_tcp_close ( gnrc_tcp_tcb_t * tcb )

Close a TCP connection.

Precondition: gnrc_tcp_tcb_init() must have been successfully called.; tcb must not be NULL.

Parameters

[in,out] tcb TCB holding the connection information.

◆ gnrc_tcp_ep_from_str()

int gnrc_tcp_ep_from_str	(	gnrc_tcp_ep_t *	ep,
		const char *	str )

Construct TCP connection endpoint from string.

Note

This function expects str in the IPv6 "URL" notation. The following strings specify a valid endpoint:

[fe80::0a00:27ff:fe9f:7a5b%5]:8080 (with Port and Interface)
[2001::0200:f8ff:fe21:67cf]:8080 (with Port)
[2001::0200:f8ff:fe21:67cf] (addr only)

Parameters

[in,out]	ep	Endpoint to initialize.
[in]	str	String containing IPv6-Address to parse.

Returns: 0 on success.; -EINVAL if parsing of str failed.

◆ gnrc_tcp_ep_init()

int gnrc_tcp_ep_init	(	gnrc_tcp_ep_t *	ep,
		int	family,
		const uint8_t *	addr,
		size_t	addr_size,
		uint16_t	port,
		uint16_t	netif )

Initialize TCP connection endpoint.

Parameters

[in,out]	ep	Endpoint to initialize.
[in]	family	Address family of `addr`.
[in]	addr	Address for endpoint.
[in]	addr_size	Size of `addr`.
[in]	port	Port number for endpoint.
[in]	netif	Network interface to use.

Returns: 0 on success.; -EAFNOSUPPORT if address_family is not supported.; -EINVAL if addr_size does not match family.

◆ gnrc_tcp_get_local()

int gnrc_tcp_get_local	(	gnrc_tcp_tcb_t *	tcb,
		gnrc_tcp_ep_t *	ep )

Get the local end point of a connected TCB.

Precondition: tcb must not be NULL; ep must not be NULL

Parameters

[in]	tcb	TCB holding the connection information.
[out]	ep	The local end point.

Returns: 0 on success.; -EADDRNOTAVAIL, when tcb in not in a connected state.

◆ gnrc_tcp_get_remote()

int gnrc_tcp_get_remote	(	gnrc_tcp_tcb_t *	tcb,
		gnrc_tcp_ep_t *	ep )

Get the remote end point of a connected TCB.

Precondition: tcb must not be NULL; ep must not be NULL

Parameters

[in]	tcb	TCB holding the connection information.
[out]	ep	The remote end point.

Returns: 0 on success.; -ENOTCONN, when tcb in not in a connected state.

◆ gnrc_tcp_hdr_build()

gnrc_pktsnip_t * gnrc_tcp_hdr_build	(	gnrc_pktsnip_t *	payload,
		uint16_t	src,
		uint16_t	dst )

Adds a TCP header to a given payload.

Parameters

[in]	payload	Payload that follows the TCP header.
[in]	src	Source port number.
[in]	dst	Destination port number.

Returns: Not NULL on success.; NULL if TCP header was not allocated.

◆ gnrc_tcp_init()

int gnrc_tcp_init ( void )

Initialize TCP.

Returns: PID of TCP thread on success; -1 if TCB is already running.; -EINVAL, if priority is greater than or equal SCHED_PRIO_LEVELS; -EOVERFLOW, if there are too many threads running.

◆ gnrc_tcp_listen()

int gnrc_tcp_listen	(	gnrc_tcp_tcb_queue_t *	queue,
		gnrc_tcp_tcb_t *	tcbs,
		size_t	tcbs_len,
		const gnrc_tcp_ep_t *	local )

Configures a sequence of TCBs to wait for incoming connections.

Precondition: All TCBs behind tcbs must have been initialized via gnrc_tcp_tcb_init().; queue must not be NULL.; tcbs must not be NULL.; tcbs_len must be greater 0.; local len must be NULL.; local->port must not be 0.

Parameters

[in,out]	queue	Listening queue for incoming connections.
[in]	tcbs	TCBs associated with `queue`.
[in]	tcbs_len	Number of TCBs behind `tcbs`.
[in]	local	Endpoint specifying address and port to listen on.

Returns: 0 on success.; -EAFNOSUPPORT given address family in local is not supported.; -EINVAL address_family in tcbs and local do not match.; -EISCONN a TCB in tcbs is already connected.; -ENOMEM all available receive buffers are in use. Increase GNRC_TCP_RCV_BUFFERS.

◆ gnrc_tcp_open()

int gnrc_tcp_open	(	gnrc_tcp_tcb_t *	tcb,
		const gnrc_tcp_ep_t *	remote,
		uint16_t	local_port )

Opens a connection.

Precondition: gnrc_tcp_tcb_init() must have been successfully called.; tcb must not be NULL; remote must not be NULL.; remote->port must not be 0.

Note: Blocks until a connection was established or an error occurred.

Parameters

[in,out]	tcb	TCB for this connection.
[in]	remote	Remote endpoint to connect to.
[in]	local_port	If zero or PORT_UNSPEC, the connections source port is randomly selected. If local_port is non-zero it is used as source port.

Returns: 0 on success.; -EAFNOSUPPORT if remote address_family is not supported.; -EINVAL if remote and tcb address_family do not match or target_addr is invalid.; -EISCONN if tcb is already connected.; -ENOMEM if there are no receive buffer left to use for tcb.; -EADDRINUSE if local_port is already in use.; -ETIMEDOUT if the connection attempt timed out.; -ECONNREFUSED if the connection attempt was reset by the peer.

◆ gnrc_tcp_queue_get_local()

int gnrc_tcp_queue_get_local	(	gnrc_tcp_tcb_queue_t *	queue,
		gnrc_tcp_ep_t *	ep )

Gets the local end point of a TCB queue.

Precondition: queue must not be NULL; ep must not be NULL

Parameters

[in]	queue	TCB queue to stop listening
[out]	ep	The local end point.

Returns: 0 on success.; -EADDRNOTAVAIL, when queue has no local end point.

◆ gnrc_tcp_recv()

ssize_t gnrc_tcp_recv	(	gnrc_tcp_tcb_t *	tcb,
		void *	data,
		const size_t	max_len,
		const uint32_t	user_timeout_duration_ms )

Receive Data from the peer.

Precondition: gnrc_tcp_tcb_init() must have been successfully called.; tcb must not be NULL.; data must not be NULL.

Note: Function blocks if user_timeout_duration_us is not zero.

Parameters

[in,out]	tcb	TCB holding the connection information.
[out]	data	Pointer to the buffer where the received data should be copied into.
[in]	max_len	Maximum amount to bytes that should be read into `data`.
[in]	user_timeout_duration_ms	Timeout for receive in milliseconds. If zero and no data is available, the function returns immediately. If not zero the function blocks until data is available or `user_timeout_duration_ms` milliseconds passed. If GNRC_TCP_NO_TIMEOUT, causing the function to block until some data was available or an error occurred.

Returns: The number of bytes read into data.; 0, if the connection is closing and no further data can be read or max_len was 0.; -ENOTCONN if connection is not established.; -EAGAIN if user_timeout_duration_us is zero and no data is available.; -ECONNRESET if connection was reset by the peer.; -ECONNABORTED if the connection was aborted.; -ETIMEDOUT if user_timeout_duration_ms expired.

◆ gnrc_tcp_send()

ssize_t gnrc_tcp_send	(	gnrc_tcp_tcb_t *	tcb,
		const void *	data,
		const size_t	len,
		const uint32_t	user_timeout_duration_ms )

Transmit data to connected peer.

Precondition: gnrc_tcp_tcb_init() must have been successfully called.; tcb must not be NULL.; data must not be NULL.

Note: Blocks until up to len bytes were transmitted or an error occurred.

Parameters

[in,out]	tcb	TCB holding the connection information.
[in]	data	Pointer to the data that should be transmitted.
[in]	len	Number of bytes that should be transmitted.
[in]	user_timeout_duration_ms	If not zero and there was not data transmitted the function returns after user_timeout_duration_ms. If zero, no timeout will be triggered. If GNRC_TCP_NO_TIMEOUT the timeout is disabled causing the function to block until some data was transmitted or and error occurred.

Returns: The number of successfully transmitted bytes.; -ENOTCONN if connection is not established.; -ECONNRESET if connection was reset by the peer.; -ECONNABORTED if the connection was aborted.; -ETIMEDOUT if user_timeout_duration_ms expired.

◆ gnrc_tcp_stop_listen()

void gnrc_tcp_stop_listen ( gnrc_tcp_tcb_queue_t * queue )

Close connections and stop listening on TCB queue.

Precondition: queue must not be NULL

Note: : Blocks until all currently opened connections maintained by queue were closed.

Parameters

[in,out] queue TCB queue to stop listening

◆ gnrc_tcp_tcb_init()

void gnrc_tcp_tcb_init ( gnrc_tcp_tcb_t * tcb )

Initialize Transmission Control Block (TCB)

Precondition: tcb must not be NULL.

Parameters

[in,out] tcb TCB that should be initialized.

◆ gnrc_tcp_tcb_queue_init()

void gnrc_tcp_tcb_queue_init ( gnrc_tcp_tcb_queue_t * queue )

Initialize Transmission Control Block (TCB) queue.

Precondition: queue must not be NULL.

Parameters

[in,out] queue TCB queue to initialize.

Detailed Description

Topics

Files

Data Structures

Macros

Functions

Macro Definition Documentation

◆ GNRC_TCP_NO_TIMEOUT

Function Documentation

◆ gnrc_tcp_abort()

◆ gnrc_tcp_accept()

◆ gnrc_tcp_calc_csum()

◆ gnrc_tcp_close()

◆ gnrc_tcp_ep_from_str()

◆ gnrc_tcp_ep_init()

◆ gnrc_tcp_get_local()

◆ gnrc_tcp_get_remote()

◆ gnrc_tcp_hdr_build()

◆ gnrc_tcp_init()

◆ gnrc_tcp_listen()

◆ gnrc_tcp_open()

◆ gnrc_tcp_queue_get_local()

◆ gnrc_tcp_recv()

◆ gnrc_tcp_send()

◆ gnrc_tcp_stop_listen()

◆ gnrc_tcp_tcb_init()

◆ gnrc_tcp_tcb_queue_init()