Topics
	TCP buffer comms

	TCP packet comms

	TCP server comms

	TCP stream comms

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.

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.

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.

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

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

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

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.

void	ltrx_tcp_listener_end (struct ltrx_tcp_listener *listener)
	End listening.

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

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

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

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

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.

void	ltrx_tcp_socket_shutdown (struct ltrx_ip_socket *socket)
	Socket shutdown.

wiced_result_t	wiced_generic_start_tls_with_ciphers (wiced_tls_context_t tls_context, void referee, wiced_tls_endpoint_type_t type, wiced_tls_certificate_verification_t verification, const cipher_suite_t *cipher_list[], tls_transport_protocol_t transport_protocol)

wiced_result_t	wiced_tcp_accept (wiced_tcp_socket_t *socket)

wiced_result_t	wiced_tcp_bind (wiced_tcp_socket_t *socket, uint16_t port)

wiced_result_t	wiced_tcp_client_peer (wiced_tcp_socket_t socket, wiced_ip_address_t address, uint16_t *port)

wiced_result_t	wiced_tcp_connect (wiced_tcp_socket_t socket, const wiced_ip_address_t address, uint16_t port, uint32_t timeout_ms)

wiced_result_t	wiced_tcp_create_socket (wiced_tcp_socket_t *socket, wiced_interface_t interface)

wiced_result_t	wiced_tcp_delete_socket (wiced_tcp_socket_t *socket)

wiced_result_t	wiced_tcp_disconnect (wiced_tcp_socket_t *socket)

wiced_result_t	wiced_tcp_disconnect_with_timeout (wiced_tcp_socket_t *socket, uint32_t timeout_ms)

wiced_result_t	wiced_tcp_enable_tls (wiced_tcp_socket_t socket, void context)

wiced_result_t	wiced_tcp_listen (wiced_tcp_socket_t *socket, uint16_t port)

wiced_result_t	wiced_tcp_register_callbacks (wiced_tcp_socket_t socket, wiced_tcp_socket_callback_t connect_callback, wiced_tcp_socket_callback_t receive_callback, wiced_tcp_socket_callback_t disconnect_callback, void arg)

wiced_result_t	wiced_tcp_server_peer (wiced_tcp_socket_t socket, wiced_ip_address_t address, uint16_t *port)

void	wiced_tcp_set_type_of_service (wiced_tcp_socket_t *socket, uint32_t tos)

wiced_result_t	wiced_tcp_start_tls (wiced_tcp_socket_t *socket, wiced_tls_endpoint_type_t type, wiced_tls_certificate_verification_t verification)

wiced_result_t	wiced_tcp_unregister_callbacks (wiced_tcp_socket_t *socket)

Detailed Description

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

Communication functions for TCP (Transmission Control Protocol) Many of these are similar to the BSD-Sockets functions which are standard on POSIX

Macro Definition Documentation

◆ LTRX_TCP_LISTENER__ANY_INTERFACE

#define LTRX_TCP_LISTENER__ANY_INTERFACE 0xff

Specifies to listen on all interfaces.

Function Documentation

◆ ltrx_input_stream_init_from_open_abstract_socket()

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.

◆ ltrx_input_stream_init_from_open_tcp_socket()

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.

◆ ltrx_output_stream_init_to_open_tcp_socket()

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.

◆ ltrx_tcp_accept()

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

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

◆ ltrx_tcp_connect()

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`.

◆ ltrx_tcp_listen()

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.

◆ ltrx_tcp_listener_begin()

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`.

◆ ltrx_tcp_listener_end()

void ltrx_tcp_listener_end ( struct ltrx_tcp_listener * listener )

End listening.

Stops listening, listener is no longer used.

Parameters

listener [in,out] Listener structure.

◆ ltrx_tcp_socket_close()

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

	socket	[in,out] 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.

◆ ltrx_tcp_socket_is_closed()

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.

◆ ltrx_tcp_socket_is_eof()

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.

◆ ltrx_tcp_socket_send()

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

	sock	[in,out] 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.

◆ ltrx_tcp_socket_send_nonblocking()

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

	socket	[in,out] 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.

◆ ltrx_tcp_socket_shutdown()

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

socket [in,out] The socket.

◆ wiced_generic_start_tls_with_ciphers()

wiced_result_t wiced_generic_start_tls_with_ciphers	(	wiced_tls_context_t *	tls_context,
		void *	referee,
		wiced_tls_endpoint_type_t	type,
		wiced_tls_certificate_verification_t	verification,
		const cipher_suite_t *	cipher_list[],
		tls_transport_protocol_t	transport_protocol )

Start TLS on a TCP Connection with a particular set of cipher suites

Start Transport Layer Security (successor to SSL) on a TCP Connection

Parameters

[in,out]	tls_context	: The tls context to work with
[in,out]	referee	: Transport reference - e.g. TCP socket or EAP context
[in]	type	: Identifies whether the device will be TLS client or server
[in]	verification	: Indicates whether to verify the certificate chain against a root server.
[in]	cipher_list	: A list of cipher suites. Null terminated. e.g. static const cipher_suite_t* my_ciphers[] = { &TLS_RSA_WITH_AES_128_CBC_SHA, &TLS_RSA_WITH_AES_256_CBC_SHA, 0 };
[in]	transport_protocol	: Which type of transport to use - e.g. TCP, UDP, EAP

Returns: wiced_result_t

◆ wiced_tcp_accept()

wiced_result_t wiced_tcp_accept ( wiced_tcp_socket_t * socket )

Wait for a remote client and establish TCP connection

Sleeps until a remote client to connects to the given socket.

Parameters

[in,out] socket : A pointer to a socket handle that has been previously listened with wiced_tcp_listen

Returns: wiced_result_t

◆ wiced_tcp_bind()

wiced_result_t wiced_tcp_bind	(	wiced_tcp_socket_t *	socket,
		uint16_t	port )

Binds a TCP socket to a local TCP port

Binds a TCP socket to a local port.

Parameters

[in,out]	socket	: A pointer to a socket handle that has been previously created with wiced_tcp_create_socket
[in]	port	: The TCP port number on the local device. Can be WICED_ANY_PORT if it is not important.

Returns: wiced_result_t

◆ wiced_tcp_client_peer()

wiced_result_t wiced_tcp_client_peer	(	wiced_tcp_socket_t *	socket,
		wiced_ip_address_t *	address,
		uint16_t *	port )

Returns the details( ip address and the source port) of the server to which the client is connected to

Parameters

[in]	socket	: A pointer to a socket handle that has been previously created with wiced_tcp_create_socket
[out]	address	Returned IP address of the connected server
[out]	port	: Returned source port of the connected server

Returns: wiced_result_t

◆ wiced_tcp_connect()

wiced_result_t wiced_tcp_connect	(	wiced_tcp_socket_t *	socket,
		const wiced_ip_address_t *	address,
		uint16_t	port,
		uint32_t	timeout_ms )

Connects a client TCP socket to a remote server

Connects an existing client TCP socket to a specific remote server TCP port

Parameters

[in,out]	socket	: A pointer to a socket handle that has been previously created with wiced_tcp_create_socket
[in]	address	: The IP address of the remote server to which the connection should be made
[in]	port	: The TCP port number on the remote server
[in]	timeout_ms	: Timeout period in milliseconds

Returns: wiced_result_t

◆ wiced_tcp_create_socket()

wiced_result_t wiced_tcp_create_socket	(	wiced_tcp_socket_t *	socket,
		wiced_interface_t	interface )

Create a new TCP socket

Creates a new TCP socket. Additional steps required for the socket to become active:

Client socket:

bind - the socket needs to be bound to a local port ( usually WICED_ANY_PORT )
connect - connect to a specific remote IP & TCP port

Server socket:

listen - opens a specific local port and attaches socket to it.
accept - waits for a remote client to establish a connection

Parameters

[out]	socket	: A pointer to a UDP socket structure which will receive the created socket handle
[in]	interface	: The interface (AP or STA) for which the socket should be created

Returns: wiced_result_t

◆ wiced_tcp_delete_socket()

wiced_result_t wiced_tcp_delete_socket ( wiced_tcp_socket_t * socket )

Deletes a TCP socket

Deletes a TCP socket. Socket must be either never opened or disconnected.

Parameters

[in,out] socket : The open TCP socket to delete

Returns: wiced_result_t

◆ wiced_tcp_disconnect()

wiced_result_t wiced_tcp_disconnect ( wiced_tcp_socket_t * socket )

Disconnect a TCP connection

Disconnects a TCP connection from a remote host using the default timeout

Parameters

[in,out] socket : The open TCP socket to disconnect

Returns: wiced_result_t

◆ wiced_tcp_disconnect_with_timeout()

wiced_result_t wiced_tcp_disconnect_with_timeout	(	wiced_tcp_socket_t *	socket,
		uint32_t	timeout_ms )

Disconnect a TCP connection

Disconnects a TCP connection from a remote host using the specified timeout

Parameters

[in,out]	socket	: The open TCP socket to disconnect
[in]	timeout_ms	: Timeout period in milliseconds

Returns: wiced_result_t

◆ wiced_tcp_enable_tls()

wiced_result_t wiced_tcp_enable_tls	(	wiced_tcp_socket_t *	socket,
		void *	context )

Enable TLS on a TCP server socket

Enable Transport Layer Security (successor to SSL) on a TCP socket with a pre-existing TLS context

Note: : if socket is not yet connected with wiced_tcp_accept , then a call to wiced_tcp_accept will cause TLS to start. Otherwise, if a connection is already established, you will need to call wiced_tcp_start_tls to begin TLS communication.

Parameters

[in,out]	socket	: The TCP socket to use for TLS
[in]	context	: The TLS context to use for security.

Returns: wiced_result_t

◆ wiced_tcp_listen()

wiced_result_t wiced_tcp_listen	(	wiced_tcp_socket_t *	socket,
		uint16_t	port )

Opens a specific local port and attaches a socket to listen on it.

Parameters

[in,out]	socket	: A pointer to a socket handle that has been previously created with wiced_tcp_create_socket
[in]	port	: The TCP port number on the local device

Returns: wiced_result_t

◆ wiced_tcp_register_callbacks()

wiced_result_t wiced_tcp_register_callbacks	(	wiced_tcp_socket_t *	socket,
		wiced_tcp_socket_callback_t	connect_callback,
		wiced_tcp_socket_callback_t	receive_callback,
		wiced_tcp_socket_callback_t	disconnect_callback,
		void *	arg )

Registers a callback function with the indicated TCP socket

Parameters

[in,out]	socket	: A pointer to a TCP socket handle that has been previously created with wiced_tcp_create_socket
[in]	connect_callback	: The function that will be called when a new request from client comes in for server. It will be only used/called when WICED device is acting as a server. It is not used and reserved for future use when WICED device is acting as a client.
[in]	receive_callback	: The function that will be called when a new packet is received by the TCP socket
[in]	disconnect_callback	: The function that will be called when the TCP socket is disconnected
[in]	arg	: The argument that will be passed to the callbacks

Returns: wiced_result_t

◆ wiced_tcp_server_peer()

wiced_result_t wiced_tcp_server_peer	(	wiced_tcp_socket_t *	socket,
		wiced_ip_address_t *	address,
		uint16_t *	port )

Returns the details( ip address and the source port) of the client which is connected currently to a server

Parameters

[in]	socket	: A pointer to a socket handle that has been previously created with wiced_tcp_create_socket
[out]	address	Returned IP address of the connected client
[out]	port	: Returned source port of the connected client

Returns: wiced_result_t

◆ wiced_tcp_set_type_of_service()

void wiced_tcp_set_type_of_service	(	wiced_tcp_socket_t *	socket,
		uint32_t	tos )

Sets the type of service for the indicated TCP socket

Parameters

[in,out]	socket	: A pointer to a TCP socket handle that has been previously created with wiced_tcp_create_socket
[in]	tos	: The type of service, where 0x00 or 0xC0 = Best effort, 0x40 or 0x80 = Background, 0x20 or 0xA0 = Video, 0x60 or 0xE0 = Voice

Returns: void

◆ wiced_tcp_start_tls()

wiced_result_t wiced_tcp_start_tls	(	wiced_tcp_socket_t *	socket,
		wiced_tls_endpoint_type_t	type,
		wiced_tls_certificate_verification_t	verification )

Start TLS on a TCP Connection

Start Transport Layer Security (successor to SSL) on a TCP Connection

Parameters

[in,out]	socket	: The TCP socket to use for TLS
[in]	type	: Identifies whether the device will be TLS client or server
[in]	verification	: Indicates whether to verify the certificate chain against a root server.

Returns: wiced_result_t

◆ wiced_tcp_unregister_callbacks()

wiced_result_t wiced_tcp_unregister_callbacks ( wiced_tcp_socket_t * socket )

Un-registers all callback functions associated with the indicated TCP socket

Parameters

[in,out] socket : A pointer to a TCP socket handle that has been previously created with wiced_tcp_create_socket

Returns: wiced_result_t

Topics

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ LTRX_TCP_LISTENER__ANY_INTERFACE

Function Documentation

◆ ltrx_input_stream_init_from_open_abstract_socket()

◆ ltrx_input_stream_init_from_open_tcp_socket()

◆ ltrx_output_stream_init_to_open_tcp_socket()

◆ ltrx_tcp_accept()

◆ ltrx_tcp_connect()

◆ ltrx_tcp_listen()

◆ ltrx_tcp_listener_begin()

◆ ltrx_tcp_listener_end()

◆ ltrx_tcp_socket_close()

◆ ltrx_tcp_socket_is_closed()

◆ ltrx_tcp_socket_is_eof()

◆ ltrx_tcp_socket_send()

◆ ltrx_tcp_socket_send_nonblocking()

◆ ltrx_tcp_socket_shutdown()

◆ wiced_generic_start_tls_with_ciphers()

◆ wiced_tcp_accept()

◆ wiced_tcp_bind()

◆ wiced_tcp_client_peer()

◆ wiced_tcp_connect()

◆ wiced_tcp_create_socket()

◆ wiced_tcp_delete_socket()

◆ wiced_tcp_disconnect()

◆ wiced_tcp_disconnect_with_timeout()

◆ wiced_tcp_enable_tls()

◆ wiced_tcp_listen()

◆ wiced_tcp_register_callbacks()

◆ wiced_tcp_server_peer()

◆ wiced_tcp_set_type_of_service()

◆ wiced_tcp_start_tls()

◆ wiced_tcp_unregister_callbacks()