lwIP  2.0.2
Lightweight IP stack

Macros

#define tcp_nagle_disable(pcb)   ((pcb)->flags |= TF_NODELAY)
 
#define tcp_nagle_enable(pcb)   ((pcb)->flags = (tcpflags_t)((pcb)->flags & ~TF_NODELAY))
 
#define tcp_nagle_disabled(pcb)   (((pcb)->flags & TF_NODELAY) != 0)
 
#define tcp_listen(pcb)   tcp_listen_with_backlog(pcb, TCP_DEFAULT_LISTEN_BACKLOG)
 

Functions

void tcp_backlog_delayed (struct tcp_pcb *pcb)
 
void tcp_backlog_accepted (struct tcp_pcb *pcb)
 
err_t tcp_close (struct tcp_pcb *pcb)
 
err_t tcp_shutdown (struct tcp_pcb *pcb, int shut_rx, int shut_tx)
 
void tcp_abort (struct tcp_pcb *pcb)
 
err_t tcp_bind (struct tcp_pcb *pcb, const ip_addr_t *ipaddr, u16_t port)
 
struct tcp_pcbtcp_listen_with_backlog (struct tcp_pcb *pcb, u8_t backlog)
 
struct tcp_pcbtcp_listen_with_backlog_and_err (struct tcp_pcb *pcb, u8_t backlog, err_t *err)
 
void tcp_recved (struct tcp_pcb *pcb, u16_t len)
 
err_t tcp_connect (struct tcp_pcb *pcb, const ip_addr_t *ipaddr, u16_t port, tcp_connected_fn connected)
 
struct tcp_pcbtcp_new (void)
 
struct tcp_pcbtcp_new_ip_type (u8_t type)
 
void tcp_arg (struct tcp_pcb *pcb, void *arg)
 
void tcp_recv (struct tcp_pcb *pcb, tcp_recv_fn recv)
 
void tcp_sent (struct tcp_pcb *pcb, tcp_sent_fn sent)
 
void tcp_err (struct tcp_pcb *pcb, tcp_err_fn err)
 
void tcp_accept (struct tcp_pcb *pcb, tcp_accept_fn accept)
 
void tcp_poll (struct tcp_pcb *pcb, tcp_poll_fn poll, u8_t interval)
 
err_t tcp_write (struct tcp_pcb *pcb, const void *arg, u16_t len, u8_t apiflags)
 
err_t tcp_output (struct tcp_pcb *pcb)
 

Detailed Description

Transmission Control Protocol for IP

See also
lwIP API and Netconn API

Common functions for the TCP implementation, such as functinos for manipulating the data structures and the TCP timer functions. TCP functions related to input and output is found in tcp_in.c and tcp_out.c respectively.

Macro Definition Documentation

◆ tcp_listen

#define tcp_listen (   pcb)    tcp_listen_with_backlog(pcb, TCP_DEFAULT_LISTEN_BACKLOG)

◆ tcp_nagle_disable

#define tcp_nagle_disable (   pcb)    ((pcb)->flags |= TF_NODELAY)

◆ tcp_nagle_disabled

#define tcp_nagle_disabled (   pcb)    (((pcb)->flags & TF_NODELAY) != 0)

◆ tcp_nagle_enable

#define tcp_nagle_enable (   pcb)    ((pcb)->flags = (tcpflags_t)((pcb)->flags & ~TF_NODELAY))

Function Documentation

◆ tcp_abort()

void tcp_abort ( struct tcp_pcb pcb)

Aborts the connection by sending a RST (reset) segment to the remote host. The pcb is deallocated. This function never fails.

ATTENTION: When calling this from one of the TCP callbacks, make sure you always return ERR_ABRT (and never return ERR_ABRT otherwise or you will risk accessing deallocated memory or memory leaks!

Parameters
pcbthe tcp pcb to abort

◆ tcp_accept()

void tcp_accept ( struct tcp_pcb pcb,
tcp_accept_fn  accept 
)

Used for specifying the function that should be called when a LISTENing connection has been connected to another host.

Parameters
pcbtcp_pcb to set the accept callback
acceptcallback function to call for this pcb when LISTENing connection has been connected to another host

◆ tcp_arg()

void tcp_arg ( struct tcp_pcb pcb,
void *  arg 
)

Used to specify the argument that should be passed callback functions.

Parameters
pcbtcp_pcb to set the callback argument
argvoid pointer argument to pass to callback functions

◆ tcp_backlog_accepted()

void tcp_backlog_accepted ( struct tcp_pcb pcb)

A delayed-accept a connection is accepted (or closed/aborted): decreases the number of outstanding connections after calling tcp_backlog_delayed().

ATTENTION: the caller is responsible for calling tcp_backlog_accepted() or else the backlog feature will get out of sync!

Parameters
pcbthe connection pcb which is now fully accepted (or closed/aborted)

◆ tcp_backlog_delayed()

void tcp_backlog_delayed ( struct tcp_pcb pcb)

Delay accepting a connection in respect to the listen backlog: the number of outstanding connections is increased until tcp_backlog_accepted() is called.

ATTENTION: the caller is responsible for calling tcp_backlog_accepted() or else the backlog feature will get out of sync!

Parameters
pcbthe connection pcb which is not fully accepted yet

◆ tcp_bind()

err_t tcp_bind ( struct tcp_pcb pcb,
const ip_addr_t ipaddr,
u16_t  port 
)

Binds the connection to a local port number and IP address. If the IP address is not given (i.e., ipaddr == NULL), the IP address of the outgoing network interface is used instead.

Parameters
pcbthe tcp_pcb to bind (no check is done whether this pcb is already bound!)
ipaddrthe local ip address to bind to (use IP4_ADDR_ANY to bind to any local address
portthe local port to bind to
Returns
ERR_USE if the port is already in use ERR_VAL if bind failed because the PCB is not in a valid state ERR_OK if bound

◆ tcp_close()

err_t tcp_close ( struct tcp_pcb pcb)

Closes the connection held by the PCB.

Listening pcbs are freed and may not be referenced any more. Connection pcbs are freed if not yet connected and may not be referenced any more. If a connection is established (at least SYN received or in a closing state), the connection is closed, and put in a closing state. The pcb is then automatically freed in tcp_slowtmr(). It is therefore unsafe to reference it (unless an error is returned).

Parameters
pcbthe tcp_pcb to close
Returns
ERR_OK if connection has been closed another err_t if closing failed and pcb is not freed

◆ tcp_connect()

err_t tcp_connect ( struct tcp_pcb pcb,
const ip_addr_t ipaddr,
u16_t  port,
tcp_connected_fn  connected 
)

Connects to another host. The function given as the "connected" argument will be called when the connection has been established.

Parameters
pcbthe tcp_pcb used to establish the connection
ipaddrthe remote ip address to connect to
portthe remote tcp port to connect to
connectedcallback function to call when connected (on error, the err calback will be called)
Returns
ERR_VAL if invalid arguments are given ERR_OK if connect request has been sent other err_t values if connect request couldn't be sent

◆ tcp_err()

void tcp_err ( struct tcp_pcb pcb,
tcp_err_fn  err 
)

Used to specify the function that should be called when a fatal error has occurred on the connection.

Note
The corresponding pcb is already freed when this callback is called!
Parameters
pcbtcp_pcb to set the err callback
errcallback function to call for this pcb when a fatal error has occurred on the connection

◆ tcp_listen_with_backlog()

struct tcp_pcb* tcp_listen_with_backlog ( struct tcp_pcb pcb,
u8_t  backlog 
)

Set the state of the connection to be LISTEN, which means that it is able to accept incoming connections. The protocol control block is reallocated in order to consume less memory. Setting the connection to LISTEN is an irreversible process.

Parameters
pcbthe original tcp_pcb
backlogthe incoming connections queue limit
Returns
tcp_pcb used for listening, consumes less memory.
Note
The original tcp_pcb is freed. This function therefore has to be called like this: tpcb = tcp_listen_with_backlog(tpcb, backlog);

◆ tcp_listen_with_backlog_and_err()

struct tcp_pcb* tcp_listen_with_backlog_and_err ( struct tcp_pcb pcb,
u8_t  backlog,
err_t err 
)

Set the state of the connection to be LISTEN, which means that it is able to accept incoming connections. The protocol control block is reallocated in order to consume less memory. Setting the connection to LISTEN is an irreversible process.

Parameters
pcbthe original tcp_pcb
backlogthe incoming connections queue limit
errwhen NULL is returned, this contains the error reason
Returns
tcp_pcb used for listening, consumes less memory.
Note
The original tcp_pcb is freed. This function therefore has to be called like this: tpcb = tcp_listen_with_backlog_and_err(tpcb, backlog, &err);

◆ tcp_new()

struct tcp_pcb* tcp_new ( void  )

Creates a new TCP protocol control block but doesn't place it on any of the TCP PCB lists. The pcb is not put on any list until binding using tcp_bind().

◆ tcp_new_ip_type()

struct tcp_pcb* tcp_new_ip_type ( u8_t  type)

Creates a new TCP protocol control block but doesn't place it on any of the TCP PCB lists. The pcb is not put on any list until binding using tcp_bind().

Parameters
typeIP address type, see lwip_ip_addr_type definitions. If you want to listen to IPv4 and IPv6 (dual-stack) connections, supply IPADDR_TYPE_ANY as argument and bind to IP_ANY_TYPE.
Returns
a new tcp_pcb that initially is in state CLOSED

◆ tcp_output()

err_t tcp_output ( struct tcp_pcb pcb)

Find out what we can send and send it

Parameters
pcbProtocol control block for the TCP connection to send data
Returns
ERR_OK if data has been sent or nothing to send another err_t on error

◆ tcp_poll()

void tcp_poll ( struct tcp_pcb pcb,
tcp_poll_fn  poll,
u8_t  interval 
)

Used to specify the function that should be called periodically from TCP. The interval is specified in terms of the TCP coarse timer interval, which is called twice a second.

◆ tcp_recv()

void tcp_recv ( struct tcp_pcb pcb,
tcp_recv_fn  recv 
)

Used to specify the function that should be called when a TCP connection receives data.

Parameters
pcbtcp_pcb to set the recv callback
recvcallback function to call for this pcb when data is received

◆ tcp_recved()

void tcp_recved ( struct tcp_pcb pcb,
u16_t  len 
)

This function should be called by the application when it has processed the data. The purpose is to advertise a larger window when the data has been processed.

Parameters
pcbthe tcp_pcb for which data is read
lenthe amount of bytes that have been read by the application

◆ tcp_sent()

void tcp_sent ( struct tcp_pcb pcb,
tcp_sent_fn  sent 
)

Used to specify the function that should be called when TCP data has been successfully delivered to the remote host.

Parameters
pcbtcp_pcb to set the sent callback
sentcallback function to call for this pcb when data is successfully sent

◆ tcp_shutdown()

err_t tcp_shutdown ( struct tcp_pcb pcb,
int  shut_rx,
int  shut_tx 
)

Causes all or part of a full-duplex connection of this PCB to be shut down. This doesn't deallocate the PCB unless shutting down both sides! Shutting down both sides is the same as calling tcp_close, so if it succeds, the PCB should not be referenced any more.

Parameters
pcbPCB to shutdown
shut_rxshut down receive side if this is != 0
shut_txshut down send side if this is != 0
Returns
ERR_OK if shutdown succeeded (or the PCB has already been shut down) another err_t on error.

◆ tcp_write()

err_t tcp_write ( struct tcp_pcb pcb,
const void *  arg,
u16_t  len,
u8_t  apiflags 
)

Write data for sending (but does not send it immediately).

It waits in the expectation of more data being sent soon (as it can send them more efficiently by combining them together). To prompt the system to send data now, call tcp_output() after calling tcp_write().

Parameters
pcbProtocol control block for the TCP connection to enqueue data for.
argPointer to the data to be enqueued for sending.
lenData length in bytes
apiflagscombination of following flags :
  • TCP_WRITE_FLAG_COPY (0x01) data will be copied into memory belonging to the stack
  • TCP_WRITE_FLAG_MORE (0x02) for TCP connection, PSH flag will not be set on last segment sent,
Returns
ERR_OK if enqueued, another err_t on error