TCP protocol support
[Protocol stack]

Detailed Description

Implementation of the TCP protocol.

For each listening port and each connection there exists a TCP socket. Sockets are allocated using tcp_socket_alloc() and deallocated with tcp_socket_free(). Each socket has a callback function associated with it. This function is called whenever an event happens on the socket. The callback function then acts on this event.

To listen for incoming connections on a specific port, call tcp_listen() on a socket. When a remote host wants to establish a connection, an event is generated and tcp_accept() should be called to accept the connection. In this case, a new socket is automatically allocated for the connection.

To actively connect to a remote host, call tcp_connect() and wait for an event signalling a successful connection attempt.

Use tcp_write() and tcp_read() to send and receive data over a socket. Events are generated whenever data was successfully sent or received. Use tcp_buffer_used_rx() to check how much data is waiting to be read from a socket.

Files

file tcp.c

TCP implementation (license: GPLv2).

file tcp.h

TCP header (license: GPLv2).

file tcp_queue.c

TCP data queue implementation (license: GPLv2).

file tcp_queue.h

TCP data queue header (license: GPLv2).

Modules

TCP configuration

Enumerations

enum tcp_event {
  TCP_EVT_NONE, TCP_EVT_ERROR, TCP_EVT_RESET, TCP_EVT_TIMEOUT,
  TCP_EVT_CONN_ESTABLISHED, TCP_EVT_CONN_INCOMING, TCP_EVT_CONN_CLOSED, TCP_EVT_CONN_IDLE,
  TCP_EVT_DATA_RECEIVED, TCP_EVT_DATA_SENT
}

Events generated by a TCP socket. More...

Functions

void tcp_init ()

Initializes the TCP layer.

bool tcp_handle_packet (const uint8_t *ip, const struct tcp_header *packet, uint16_t packet_len)

Forwards incoming packets to the appropriate TCP socket.

int tcp_socket_alloc (tcp_callback callback)

Allocates a TCP socket.

bool tcp_socket_free (int socket)

Deallocates a TCP socket.

bool tcp_connect (int socket, const uint8_t *ip, uint16_t port)

Actively opens a connection to the given remote host and port.

bool tcp_disconnect (int socket)

Actively closes a connection.

bool tcp_listen (int socket, uint16_t port)

Starts listening on a local port for incoming connections.

bool tcp_accept (int socket, tcp_callback callback)

Accepts an incoming connection.

int16_t tcp_write (int socket, const uint8_t *data, uint16_t data_len)

Writes data for transmission to the socket.

int16_t tcp_write_string_P (int socket, PGM_P str)

Writes a string from flash memory space to the socket.

int16_t tcp_read (int socket, uint8_t *buffer, uint16_t buffer_len)

Reads data which was received over a socket.

int16_t tcp_peek (int socket, uint8_t *buffer, uint16_t offset, uint16_t buffer_len)

Reads data which was received over a socket, without actually removing it from the input buffer.

int16_t tcp_skip (int socket, uint16_t len)

Removes data from the receive buffer of a socket without reading it.

int16_t tcp_reserve (int socket, uint16_t len)

Declares unused transmit buffer space of a socket as valid.

uint8_t * tcp_buffer_rx (int socket)

Retrieves a pointer to the occupied part of the receive buffer space of a socket.

uint8_t * tcp_buffer_tx (int socket)

Retrieves a pointer to the empty part of the transmit buffer space of a socket.

int16_t tcp_buffer_used_rx (int socket)

Retrieves the number of available data bytes waiting to be read from the socket.

int16_t tcp_buffer_space_rx (int socket)

Retrieves the number of data bytes which currently can be received until the receive buffer of the socket is full.

int16_t tcp_buffer_used_tx (int socket)

Retrieves the number of data bytes which have been written to the socket but which have not been sent to the remote host or which have not been acknowledged yet.

int16_t tcp_buffer_space_tx (int socket)

Retrieves the number of data bytes which currently can be written to the socket.

Enumeration Type Documentation

enum tcp_event

Events generated by a TCP socket.

Enumerator:

TCP_EVT_NONE	No event happened.
TCP_EVT_ERROR	Some error happened. The socket is no more usable and should be deallocated.
TCP_EVT_RESET	The connection has been closed down unexpectedly.
TCP_EVT_TIMEOUT	The connection has timed out and has been closed.
TCP_EVT_CONN_ESTABLISHED	The connection has been established and is ready for sending and receiving data.
TCP_EVT_CONN_INCOMING	A connection attempt has been made by a remote host.
TCP_EVT_CONN_CLOSED	The connection has been closed.
TCP_EVT_CONN_IDLE	The connection is idle.
TCP_EVT_DATA_RECEIVED	Incoming data is waiting to be read from the socket.
TCP_EVT_DATA_SENT	Data which has been previously written to the socket has been sent.

Function Documentation

bool tcp_handle_packet	(	const uint8_t *	ip,
		const struct tcp_header *	packet,
		uint16_t	packet_len
	)

Forwards incoming packets to the appropriate TCP socket.

Note:: This function is used internally and should not be explicitly called by applications.

Returns:: true if a matching socket was found, false if the packet was discarded.

int tcp_socket_alloc ( tcp_callback callback )

Allocates a TCP socket.

The given callback function will be called whenever an event is generated for the socket.

Parameters:

[in] callback A pointer to the event callback function.

Returns:: A non-negative socket identifier on success, -1 on failure.

bool tcp_socket_free ( int socket )

Deallocates a TCP socket.

After freeing the socket it can no longer be used.

Parameters:

[in] socket The identifier of the socket to deallocate.

Returns:: true if the socket has been deallocated, false on failure.

bool tcp_connect	(	int	socket,
		const uint8_t *	ip,
		uint16_t	port
	)

Actively opens a connection to the given remote host and port.

When the connection was successfully established, a TCP_EVT_CONN_ESTABLISHED event is generated for the socket.

Parameters:

`[in]`	socket	The identifier of the socket over which the connection will be established.
`[in]`	ip	The buffer containing the remote IP address.
`[in]`	port	The port on the remote host.

Returns:: true if the connection initiation was started successfully, false otherwise.

bool tcp_disconnect ( int socket )

Actively closes a connection.

When the connection has been closed, a TCP_EVT_CONN_CLOSED event is generated for the socket.

Parameters:

[in] socket The identifier of the socket whose connection should get closed.

Returns:: true if the connection shutdown was started successfully, false otherwise.

bool tcp_listen	(	int	socket,
		uint16_t	port
	)

Starts listening on a local port for incoming connections.

When an incoming connection is detected, a TCP_EVT_CONN_INCOMING event is generated for the socket and tcp_accept() should be called to accept the connection.

Parameters:

`[in]`	socket	The identifier of the port on which to listen for connections.
`[in]`	port	The number of the port on which to listen.

Returns:: true if the socket now listens for connections, false otherwise.

bool tcp_accept	(	int	socket,
		tcp_callback	callback
	)

Accepts an incoming connection.

This function has to be called in the event callback function of a listening socket when a TCP_EVT_CONN_INCOMING event is being handled. tcp_accept() returns a new socket which is from now on used to handle the new connection. The given callback function is attached to this new socket.

Parameters:

`[in]`	socket	The identifier of the listening socket for which the event was generated.
`[in]`	callback	The callback function which should be attached to the new socket.

Returns:: The non-negative identifier of the new socket on success, -1 on failure.

int16_t tcp_write	(	int	socket,
		const uint8_t *	data,
		uint16_t	data_len
	)

Writes data for transmission to the socket.

When (part of) the data has been successfully sent and acknowledged by the remote host, a TCP_EVT_DATA_SENT event is generated for the socket.

Parameters:

`[in]`	socket	The identifier of the socket over which the data will be sent.
`[in]`	data	A pointer to the buffer which contains the data to be sent.
`[in]`	data_len	The number of data bytes to send.

Returns:: The non-negative number of bytes queued for transmission on success, -1 on failure.

int16_t tcp_write_string_P	(	int	socket,
		PGM_P	str
	)

Writes a string from flash memory space to the socket.

When (part of) the data has been successfully sent and acknowledged by the remote host, a TCP_EVT_DATA_SENT event is generated for the socket.

Parameters:

`[in]`	socket	The identifier of the socket over which the data will be sent.
`[in]`	str	A pointer to the string in flash memory space.

Returns:: The non-negative number of bytes queued for transmission on success, -1 on failure.

int16_t tcp_read	(	int	socket,
		uint8_t *	buffer,
		uint16_t	buffer_len
	)

Reads data which was received over a socket.

This function is usually used in response to a TCP_EVT_DATA_RECEIVED event which has been generated for the socket.

Parameters:

`[in]`	socket	The identifier of the socket from which the data should be read.
`[out]`	buffer	A pointer to the buffer to which the received data should be written.
`[in]`	buffer_len	The maximum number of bytes to read from the socket.

Returns:: The non-negative number of bytes actually written to the buffer on success, -1 on failure.

int16_t tcp_peek	(	int	socket,
		uint8_t *	buffer,
		uint16_t	offset,
		uint16_t	buffer_len
	)

Reads data which was received over a socket, without actually removing it from the input buffer.

Parameters:

`[in]`	socket	The identifier of the socket from which the data should be read.
`[out]`	buffer	A pointer to the buffer to which the received data should be written.
`[in]`	offset	Skip the first offset bytes before starting to read.
`[in]`	buffer_len	The maximum number of bytes to read.

Returns:: The non-negative number of bytes actually written to the buffer on success, -1 on failure.

int16_t tcp_skip	(	int	socket,
		uint16_t	len
	)

Removes data from the receive buffer of a socket without reading it.

Parameters:

`[in]`	socket	The identifier of the socket from which the data should be removed.
`[in]`	len	The maximum number of bytes to remove.

Returns:: The number of bytes actually removed.

int16_t tcp_reserve	(	int	socket,
		uint16_t	len
	)

Declares unused transmit buffer space of a socket as valid.

This is only useful if tcp_buffer_tx() has been used before to retrieve and fill the unused buffer space with valid data.

Parameters:

`[in]`	socket	The identifier of the socket over which the data will be sent.
`[in]`	len	The number of data bytes to declare as valid.

Returns:: The number of bytes which have been declared as valid on success, -1 on failure.

uint8_t * tcp_buffer_rx ( int socket )

Retrieves a pointer to the occupied part of the receive buffer space of a socket.

The buffer is guaranteed to be linear and contiguous. Its size is retrieved with tcp_buffer_used_rx().

Note:: This function can be quite expensive, especially with a full receive buffer.

Parameters:

[in] socket The identifier of the socket of which to retrieve the occupied receive buffer space.

Returns:: A pointer to the occupied buffer space on success, NULL on failure.

uint8_t * tcp_buffer_tx ( int socket )

Retrieves a pointer to the empty part of the transmit buffer space of a socket.

The buffer is guaranteed to be linear and contiguous. Its size is retrieved with tcp_buffer_space_tx(). After writing to the buffer, be sure to call tcp_reserve() to actually add the data to the transmit buffer.

Attention:: Make sure the transmit buffer is not modified while the empty buffer space is being used.

Parameters:

[in] socket The identifier of the socket of which to retrieve the empty transmit buffer space.

Returns:: A pointer to the empty transmit buffer space on success, NULL on failure.

int16_t tcp_buffer_used_rx ( int socket )

Retrieves the number of available data bytes waiting to be read from the socket.

Parameters:

[in] socket The identifier of the socket to ask for available data.

Returns:: The non-negative number of available data bytes on success, -1 on failure.

int16_t tcp_buffer_space_rx ( int socket )

Retrieves the number of data bytes which currently can be received until the receive buffer of the socket is full.

Parameters:

[in] socket The identifier of the socket to ask for unused receive buffer space.

Returns:: The non-negative number of unused receive buffer bytes on success, -1 on failure.

int16_t tcp_buffer_used_tx ( int socket )

Retrieves the number of data bytes which have been written to the socket but which have not been sent to the remote host or which have not been acknowledged yet.

Parameters:

[in] socket The identifier of the socket of which to get the occupied transmit buffer space.

Returns:: The non-negative number of already used transmit buffer bytes on success, -1 on failure.

int16_t tcp_buffer_space_tx ( int socket )

Retrieves the number of data bytes which currently can be written to the socket.

Parameters:

[in] socket The identifier of the socket of which to get the available transmit buffer space.

Returns:: The non-negative number of unused transmit buffer bytes on success, -1 on failure.


Files
file	tcp.c
	TCP implementation (license: GPLv2).
file	tcp.h
	TCP header (license: GPLv2).
file	tcp_queue.c
	TCP data queue implementation (license: GPLv2).
file	tcp_queue.h
	TCP data queue header (license: GPLv2).
Modules
	TCP configuration
Enumerations
enum	tcp_event { TCP_EVT_NONE, TCP_EVT_ERROR, TCP_EVT_RESET, TCP_EVT_TIMEOUT, TCP_EVT_CONN_ESTABLISHED, TCP_EVT_CONN_INCOMING, TCP_EVT_CONN_CLOSED, TCP_EVT_CONN_IDLE, TCP_EVT_DATA_RECEIVED, TCP_EVT_DATA_SENT }
	Events generated by a TCP socket. More...
Functions
void	tcp_init ()
	Initializes the TCP layer.
bool	tcp_handle_packet (const uint8_t ip, const struct tcp_header packet, uint16_t packet_len)
	Forwards incoming packets to the appropriate TCP socket.
int	tcp_socket_alloc (tcp_callback callback)
	Allocates a TCP socket.
bool	tcp_socket_free (int socket)
	Deallocates a TCP socket.
bool	tcp_connect (int socket, const uint8_t *ip, uint16_t port)
	Actively opens a connection to the given remote host and port.
bool	tcp_disconnect (int socket)
	Actively closes a connection.
bool	tcp_listen (int socket, uint16_t port)
	Starts listening on a local port for incoming connections.
bool	tcp_accept (int socket, tcp_callback callback)
	Accepts an incoming connection.
int16_t	tcp_write (int socket, const uint8_t *data, uint16_t data_len)
	Writes data for transmission to the socket.
int16_t	tcp_write_string_P (int socket, PGM_P str)
	Writes a string from flash memory space to the socket.
int16_t	tcp_read (int socket, uint8_t *buffer, uint16_t buffer_len)
	Reads data which was received over a socket.
int16_t	tcp_peek (int socket, uint8_t *buffer, uint16_t offset, uint16_t buffer_len)
	Reads data which was received over a socket, without actually removing it from the input buffer.
int16_t	tcp_skip (int socket, uint16_t len)
	Removes data from the receive buffer of a socket without reading it.
int16_t	tcp_reserve (int socket, uint16_t len)
	Declares unused transmit buffer space of a socket as valid.
uint8_t *	tcp_buffer_rx (int socket)
	Retrieves a pointer to the occupied part of the receive buffer space of a socket.
uint8_t *	tcp_buffer_tx (int socket)
	Retrieves a pointer to the empty part of the transmit buffer space of a socket.
int16_t	tcp_buffer_used_rx (int socket)
	Retrieves the number of available data bytes waiting to be read from the socket.
int16_t	tcp_buffer_space_rx (int socket)
	Retrieves the number of data bytes which currently can be received until the receive buffer of the socket is full.
int16_t	tcp_buffer_used_tx (int socket)
	Retrieves the number of data bytes which have been written to the socket but which have not been sent to the remote host or which have not been acknowledged yet.
int16_t	tcp_buffer_space_tx (int socket)
	Retrieves the number of data bytes which currently can be written to the socket.

TCP protocol support [Protocol stack]

Detailed Description

Files

Modules

Enumerations

Functions

Enumeration Type Documentation

Function Documentation

TCP protocol support
[Protocol stack]