Data Structures
struct	input_stream_from_open_tcp_socket
	Concrete struct for a tcp input stream. More...

struct	ltrx_tcp_listener
	Abstract structure containing data for TCP listener. More...

struct	output_stream_from_open_tcp_socket
	Concrete struct for a tcp output stream. More...

Macros
#define	LTRX_TCP_LISTENER__ANY_INTERFACE 0xff

Functions
bool	ltrx_input_stream_init_from_open_abstract_socket (struct input_stream_from_open_abstract_socket inStream, struct ltrx_ip_socket lis, const struct ltrx_network_protocol lnp, struct ltrx_network_protocol_handle lnph)
	Construct input stream from an open socket. More...

bool	ltrx_input_stream_init_from_open_tcp_socket (struct input_stream_from_open_tcp_socket inStream, struct ltrx_ip_socket lis)
	Construct input stream from an open TCP socket. More...

bool	ltrx_output_stream_init_to_open_tcp_socket (struct output_stream_from_open_tcp_socket outStream, struct ltrx_ip_socket lis)
	Set up an output stream to an open TCP socket. More...

struct ltrx_ip_socket *	ltrx_tcp_accept (struct ltrx_tcp_listener listener, struct ltrx_trigger optReceiveEventTrigger)
	Accept a connection request. More...

struct ltrx_ip_socket *	ltrx_tcp_connect (uint16_t optLocalPort, const char remoteAddress, uint16_t remotePort, struct ltrx_trigger optReceiveEventTrigger)
	Make connection. More...

bool	ltrx_tcp_listen (const struct ltrx_tcp_listener *listener, uint32_t blockTimeMsec)
	Begin listening. More...

bool	ltrx_tcp_listener_begin (struct ltrx_tcp_listener listener, uint8_t zeroBasedInterface, uint16_t localPort, uint8_t backlog, struct ltrx_trigger optListenerTrigger)
	Begin listening. More...

void	ltrx_tcp_listener_end (struct ltrx_tcp_listener *listener)
	End listening. More...

bool	ltrx_tcp_socket_close (struct ltrx_ip_socket *socket, uint32_t lingerMsec)
	Close socket. More...

bool	ltrx_tcp_socket_is_closed (struct ltrx_ip_socket *socket)
	Is TCP socket closed? More...

bool	ltrx_tcp_socket_is_eof (struct ltrx_ip_socket *socket)
	Is receive at end of file? More...

bool	ltrx_tcp_socket_send (struct ltrx_ip_socket sock, const void data, size_t length, bool push)
	Send data. More...

enum ltrx_network_return	ltrx_tcp_socket_send_nonblocking (struct ltrx_ip_socket socket, const void data, size_t length, bool push, struct ltrx_trigger *sendTrigger)
	Send data non-blocking. More...

void	ltrx_tcp_socket_shutdown (struct ltrx_ip_socket *socket)
	Socket shutdown. More...

Detailed Description

The Transmission Control Protocol (TCP) layer provides connection management, congestion control, and reliable data stream delivery.

Macro Definition Documentation

#define LTRX_TCP_LISTENER__ANY_INTERFACE 0xff

Specifies to listen on all interfaces.

Function Documentation

bool ltrx_input_stream_init_from_open_abstract_socket	(	struct input_stream_from_open_abstract_socket *	inStream,
		struct ltrx_ip_socket *	lis,
		const struct ltrx_network_protocol *	lnp,
		struct ltrx_network_protocol_handle *	lnph
	)

Construct input stream from an open socket.

Return values

true	Success.
false	Failed.

Parameters

[out]	inStream	The concrete input stream from open socket struct.
[in]	lis	The open socket that will feed the stream.
[in]	lnp	The abstract network protocol.
[in]	lnph	The abstract network protocol instance.

bool ltrx_input_stream_init_from_open_tcp_socket	(	struct input_stream_from_open_tcp_socket *	inStream,
		struct ltrx_ip_socket *	lis
	)

Construct input stream from an open TCP socket.

Return values

true	Success.
false	Failed.

Parameters

[out]	inStream	The concrete input stream from open tcp socket struct.
[in]	lis	The open TCP socket that will feed the stream.

bool ltrx_output_stream_init_to_open_tcp_socket	(	struct output_stream_from_open_tcp_socket *	outStream,
		struct ltrx_ip_socket *	lis
	)

Set up an output stream to an open TCP socket.

Return values

true	Success.
false	Failed.

Parameters

[out]	outStream	Your tcp output stream struct to initialize.
[in]	lis	The open TCP socket that will be fed by the stream.

struct ltrx_ip_socket* ltrx_tcp_accept	(	struct ltrx_tcp_listener *	listener,
		struct ltrx_trigger *	optReceiveEventTrigger
	)

Accept a connection request.

Blocks till the accept either succeeds or fails.

Returns: Socket pointer.

Return values

NULL Failed.

Parameters

[in,out]	listener	Listener structure.
[in]	optReceiveEventTrigger	If present, the specified trigger will subsequently be signaled when data is received. Otherwise, fill it in `NULL`.

struct ltrx_ip_socket* ltrx_tcp_connect	(	uint16_t	optLocalPort,
		const char *	remoteAddress,
		uint16_t	remotePort,
		struct ltrx_trigger *	optReceiveEventTrigger
	)

Make connection.

Warning: Blocks till successful or failed to connect.

Returns: IP socket.

Return values

NULL Failed.

Parameters

[in]	optLocalPort	Provides the local port to use. If `0`, a random unused TCP port number will be assigned.
[in]	remoteAddress	The remote address to connect to. May be a DNS name or an IP address.
[in]	remotePort	The remote port to connect to.
[in]	optReceiveEventTrigger	If present, this trigger will be signalled when receive data is available. Otherwise, fill in `NULL`.

bool ltrx_tcp_listen	(	const struct ltrx_tcp_listener *	listener,
		uint32_t	blockTimeMsec
	)

Begin listening.

The listener was earlier initialized by ltrx_tcp_listener_begin().

One-shot calls this till it returns true, then can either accept or end.

Backlog calls this till it returns true, then can accept or end, and after accept can either listen again or end.

Return values

true	A connection request has arrived.
false	Nothing yet.

Parameters

[in]	listener	Listener structure.
	blockTimeMsec	Time to wait in milliseconds. For no wait (non-blocking), use `0`. To wait forever, use TIME_WAIT_FOREVER.

bool ltrx_tcp_listener_begin	(	struct ltrx_tcp_listener *	listener,
		uint8_t	zeroBasedInterface,
		uint16_t	localPort,
		uint8_t	backlog,
		struct ltrx_trigger *	optListenerTrigger
	)

Begin listening.

Initializes listener and starts listening.

Return values

true	Success, listener in use.
false	Failed, listener not used.

Parameters

[out]	listener	Listener structure to be initialized.
[in]	zeroBasedInterface	Specifies interface(s) to listen to. `NETS_SOFTAP_START` for listening only to ap0. `NETS_WLAN_START` for listening only to wlan0. LTRX_TCP_LISTENER__ANY_INTERFACE for listening to all of them. HINT: It can succeed when just one interface is up, then will not be listening to the other if it comes up later.
[in]	localPort	Local port number to listen on.
[in]	backlog	How many requests may be queued and not yet serviced before further requests are rejected. Use `0` for "one-shot" behavior, to listen only for the first connection.
[in]	optListenerTrigger	Optional trigger. If present, the trigger will be signaled when a connection request is received. Otherwise fill it in with `NULL`.

void ltrx_tcp_listener_end ( struct ltrx_tcp_listener * listener )

End listening.

Stops listening, listener is no longer used.

Parameters

[in,out] listener Listener structure.

bool ltrx_tcp_socket_close	(	struct ltrx_ip_socket *	socket,
		uint32_t	lingerMsec
	)

Close socket.

Return values

true	All data and FIN was ACKed okay.
false	Failed.

Parameters

[in,out]	socket	The socket.
[in]	lingerMsec	If `0`, close without sending any buffered data. If non-zero, send data, FIN, wait for ACK, send ACKs till timed out.

bool ltrx_tcp_socket_is_closed ( struct ltrx_ip_socket * socket )

Is TCP socket closed?

Return values

true	The socket is closed.
false	The socket is open.

Parameters

[in] socket The socket.

bool ltrx_tcp_socket_is_eof ( struct ltrx_ip_socket * socket )

Is receive at end of file?

Checks if all receive data has been read and a FIN has been received. This may be called after the TCP connection has been established.

Return values

true	No more receive data will be available.
false	More data might become available.

Parameters

[in] socket the socket.

bool ltrx_tcp_socket_send	(	struct ltrx_ip_socket *	sock,
		const void *	data,
		size_t	length,
		bool	push
	)

Send data.

This is called after the TCP connection has been established.

Caution: This function may block until it either succeeds or fails.

Return values

true	Success.
false	Failed.

Parameters

[in,out]	sock	The socket.
[in]	data	Data to send.
[in]	length	Length of data to send.
[in]	push	If `true`, forces TCP to forward data now, unless no data has been buffered.

enum ltrx_network_return ltrx_tcp_socket_send_nonblocking	(	struct ltrx_ip_socket *	socket,
		const void *	data,
		size_t	length,
		bool	push,
		struct ltrx_trigger *	sendTrigger
	)

Send data non-blocking.

This is called after the TCP connection has been established.

The caller must retain the integrity of data if it sees a return code of LTRX_NETWORK_RETURN__WORKING. In this case the caller must periodically call again with length of 0 until it sees LTRX_NETWORK_RETURN__SUCCESS or LTRX_NETWORK_RETURN__FAILURE returned. The caller may use sendTrigger to expedite this periodic calling.

Note that with push of false, a return code of LTRX_NETWORK_RETURN__SUCCESS does NOT imply that the data has been transmitted, but merely buffered. To transmit the data, you will need to either call this with push of true, or call ltrx_tcp_socket_close() with sufficient lingerMsec to send the data.

Return values

LTRX_NETWORK_RETURN__WORKING	Operation in progress.
LTRX_NETWORK_RETURN__SUCCESS	Success.
LTRX_NETWORK_RETURN__FAILURE	Failed.

Parameters

[in,out]	socket	The socket.
[in]	data	Data to send.
[in]	length	Length of data to send.
[in]	push	If `true`, force TCP to forward data now, unless no data has been buffered.
[in]	sendTrigger	This trigger may be signaled when the operation is complete.

void ltrx_tcp_socket_shutdown ( struct ltrx_ip_socket * socket )

Socket shutdown.

Application will call ltrx_tcp_socket_close() later, and expect it not to wait even though called with a timeout.

Parameters

[in,out] socket The socket.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

Function Documentation