NetBurner 3.1
TCP - Transmission Control Protocol

Modules

 TCP Socket Options
 
 TCP Socket State
 
 TCP Socket Status
 

Functions

int listen4 (IPADDR4 addr, uint16_t port, uint8_t maxpend=5)
 Listen for incoming IPv4 connections. More...
 
int accept4 (int listening_socket, IPADDR4 *address, uint16_t *port, uint16_t timeout)
 Accept an incoming IPv4 connection from a listening socket. More...
 
int listen6 (const IPADDR6 &addr, uint16_t port, uint8_t maxpend=5)
 Listen for incoming IPv6 connections. More...
 
int accept6 (int listening_socket, IPADDR6 *address, uint16_t *port, uint16_t timeout)
 Accept an incoming IPv6 connection from a listening socket. More...
 
int connect4 (IPADDR4 ipAddress, uint16_t remotePort, uint32_t timeout, IPADDR4 interfaceIpAddress)
 Connect to a remote IPv4 host. More...
 
int connect6 (const IPADDR6 &ipAddress, uint16_t remotePort, uint32_t timeout, const IPADDR6 &interfaceIpAddress)
 Connect to a remote IPv6 host. More...
 
int NoBlockConnect4 (IPADDR4 ipAddress, uint16_t remotePort, IPADDR4 interfaceIpAddress=IPADDR4::NullIP())
 Create a file descriptior and return immediately, does not wait for connection to complete. Before attempting to use the socket verify a connection was successful with TcpGetSocketState(fd). More...
 
int NoBlockConnect6 (const IPADDR6 &ipAddress, uint16_t remotePort, const IPADDR6 &interfaceIpAddress)
 Create a file descriptior and return immediately, does not wait for connection to complete. Before attempting to use the socket verify a connection was successful with TcpGetSocketState(fd). More...
 
IPADDR4 GetSocketRemoteAddr4 (int fd)
 Returns the IPv4 address of the remote host associated with the specified file descriptor. More...
 
IPADDR4 GetSocketLocalAddr4 (int fd)
 Returns the IPv4 address of the local interface associated with the connection. More...
 
IPADDR6 GetSocketRemoteAddr6 (int fd)
 Returns the IPv6 address of the remote host associated with the specified file descriptor. More...
 
IPADDR6 GetSocketLocalAddr6 (int fd)
 Returns the IPv6 address of the local interface associated with the connection. More...
 
uint16_t GetSocketRemotePort (int fd)
 Returns the port number of the remote host associated with the connection. More...
 
uint16_t GetSocketLocalPort (int fd)
 Returns the local port number associated with the connection. More...
 
uint32_t TcpGetLastRxTime (int fd)
 Returns the value of system Time Ticks when the last packet was received. Used for the TCP Keep Alive feature. More...
 
void TcpSendKeepAlive (int fd)
 Send a TCP keep alive packet to a remote host. More...
 
uint32_t TcpGetLastRxInterval (int fd)
 Returns the number of system Time Ticks since the last packet was received. This is the difference between the current system time and lastRxTime of the socket. More...
 
int GetTcpRtxCount (int fd)
 Returns the number of re-transmits that have occured on the specified connection. More...
 
int setsockoption (int fd, int option)
 Set TCP socket options. More...
 
int clrsockoption (int fd, int option)
 Clear TCP socket options. More...
 
int getsockoption (int fd)
 Returns the options for the specified TCP socket. More...
 
char SocketPeek (int fd)
 Returns the next char that would be read, 0 if no data. More...
 
int TcpGetSocketInterface (int fd)
 Return the network interface asociated with a TCP socket. More...
 
uint8_t TcpGetSocketState (int fd)
 Return the current state of a TCP socket. More...
 

Detailed Description

The NetBurner TCP Group

Function Documentation

◆ accept4()

int accept4 ( int  listening_socket,
IPADDR4 *  address,
uint16_t *  port,
uint16_t  timeout 
)

Accept an incoming IPv4 connection from a listening socket.

Calling accept() in dual stack mode will automatically select the correct IPv4/IPv6 function.

Begin listening for incoming connections. A connection must be accepted with the accept() function before they can be used. Each time a connection request is accepted is frees up another slot in the pending queue.

Parameters
listening_socketThe listening socket from which to accept the connection.
*addressPointer to an IPADDR object that will receive the IPADDR information for the connection. Can be NULL.
*portPointer to the variable that receive the port number of the connection. Can be NULL.
timeoutNumber of system Time Ticks to wait. A value of 0 waits forever.
Returns
The file descriptor of the accepted connection, or an error TCP Socket Status
int32_t fdListen = listen(INADDR_ANY, listenPort, 5);
if (fdListen > 0)
{
IPADDR clientAddress;
uint16_t clientPort;
int32_t fdAccept = accept(fdListen, &clientAddress, &clientPort, 0);
// additional processing ...
}
See also
accept6(), listen4(), listen6(), close()

◆ accept6()

int accept6 ( int  listening_socket,
IPADDR6 address,
uint16_t *  port,
uint16_t  timeout 
)

Accept an incoming IPv6 connection from a listening socket.

Calling accept() in dual stack mode will automatically select the correct IPv4/IPv6 function.

Begin listening for incoming connections. A connection must be accepted with the accept() function before they can be used. Each time a connection request is accepted is frees up another slot in the pending queue.

Parameters
listening_socketThe listening socket from which to accept the connection.
*addressPointer to an IPADDR object that will receive the IPADDR information for the connection. Can be NULL.
*portPointer to the variable that receive the port number of the connection. Can be NULL.
timeoutNumber of system Time Ticks to wait. A value of 0 waits forever.
Returns
The file descriptor of the accepted connection, or an error TCP Socket Status
int32_t fdListen = listen(INADDR_ANY, listenPort, 5);
if (fdListen > 0)
{
IPADDR clientAddress;
uint16_t clientPort;
int32_t fdAccept = accept(fdListen, &clientAddress, &clientPort, 0);
// additional processing ...
}
See also
accept4(), listen4(), listen6(), close()

◆ clrsockoption()

int clrsockoption ( int  fd,
int  option 
)

Clear TCP socket options.

Parameters
fdSocket file descriptor.
optionSocket option to clear: TCP Socket Options.
Returns
A bitmask of the options for the specified socket.
See also
setsockoption(), getsockoption(), setsocketackbuffers(), SetSocketRxBuffers(), SetSocketTxBuffers()

◆ connect4()

int connect4 ( IPADDR4  ipAddress,
uint16_t  remotePort,
uint32_t  timeout,
IPADDR4  interfaceIpAddress 
)
inline

Connect to a remote IPv4 host.

Calling connect() in dual stack mode will automatically select the correct IPv4/IPv6 function.

By default it will use the fist network interface.

Parameters
ipAddressIP address of the remote host.
remotePortPort number of the remote host.
timeoutNumber of system Time Ticks to wait. A value of 0 waits forever.
interfaceIpAddressOptional parameter to specify which local network interface to use for the connection. The default is 0, which is the first network interface in the configuration.
Returns
The file descriptor of the connection, or an error TCP Socket Status
int fd = connect( destIp, destPort, TICKS_PER_SECOND * 5);
See also
accept4(), listen4(), listen6(), close()

◆ connect6()

int connect6 ( const IPADDR6 ipAddress,
uint16_t  remotePort,
uint32_t  timeout,
const IPADDR6 interfaceIpAddress 
)
inline

Connect to a remote IPv6 host.

Calling connect() in dual stack mode will automatically select the correct IPv4/IPv6 function.

By default it will use the fist network interface.

Parameters
ipAddressIP address of the remote host.
remotePortPort number of the remote host.
timeoutNumber of system Time Ticks to wait. A value of 0 waits forever.
interfaceIpAddressOptional parameter to specify which local network interface to use for the connection. The default is 0, which is the first network interface in the configuration.
Returns
The file descriptor of the connection, or an error TCP Socket Status
int fd = connect( destIp, destPort, TICKS_PER_SECOND * 5);
See also
accept4(), listen4(), listen6(), close()

◆ GetSocketLocalAddr4()

IPADDR4 GetSocketLocalAddr4 ( int  fd)

Returns the IPv4 address of the local interface associated with the connection.

Calling GetSocketLocalAddr() in dual stack mode will automatically select the correct IPv4/IPv6 function.

Parameters
fdThe socket file descriptor.
Returns
The IP address of the remote host.
See also
GetSocketLocalAddr6()

◆ GetSocketLocalAddr6()

IPADDR6 GetSocketLocalAddr6 ( int  fd)

Returns the IPv6 address of the local interface associated with the connection.

Calling GetSocketLocalAddr() in dual stack mode will automatically select the correct IPv4/IPv6 function.

Parameters
fdThe socket file descriptor.
Returns
The IP address of the remote host.
See also
GetSocketLocalAddr6()

◆ GetSocketLocalPort()

uint16_t GetSocketLocalPort ( int  fd)

Returns the local port number associated with the connection.

Parameters
fdThe socket file descriptor.
Returns
The local port number for the connection.
See also
GetSocketRemotePort()

◆ GetSocketRemoteAddr4()

IPADDR4 GetSocketRemoteAddr4 ( int  fd)

Returns the IPv4 address of the remote host associated with the specified file descriptor.

Calling GetSocketRemoteAddr() in dual stack mode will automatically select the correct IPv4/IPv6 function.

Parameters
fdThe socket file descriptor.
Returns
The IP address of the remote host.
See also
GetSocketRemoteAddr6()

◆ GetSocketRemoteAddr6()

IPADDR6 GetSocketRemoteAddr6 ( int  fd)

Returns the IPv6 address of the remote host associated with the specified file descriptor.

Calling GetSocketRemoteAddr() in dual stack mode will automatically select the correct IPv4/IPv6 function.

Parameters
fdThe socket file descriptor.
Returns
The IP address of the remote host.
See also
GetSocketRemoteAddr4()

◆ GetSocketRemotePort()

uint16_t GetSocketRemotePort ( int  fd)

Returns the port number of the remote host associated with the connection.

Parameters
fdThe socket file descriptor.
Returns
The remote host port number.
See also
GetSocketLocalPort()

◆ getsockoption()

int getsockoption ( int  fd)

Returns the options for the specified TCP socket.

Parameters
fdSocket file descriptor.
Returns
A bitmask of the options for the specified socket.
See also
setsockoption(), clrsockoption(), setsocketackbuffers(), SetSocketRxBuffers(), SetSocketTxBuffers()

◆ GetTcpRtxCount()

int GetTcpRtxCount ( int  fd)

Returns the number of re-transmits that have occured on the specified connection.

Parameters
fdThe socket file descriptor.
Returns
The number of system Time Ticks since the last packet was received on the connection.

◆ listen4()

int listen4 ( IPADDR4  addr,
uint16_t  port,
uint8_t  maxpend = 5 
)

Listen for incoming IPv4 connections.

Calling listen() in dual stack mode will automatically select the correct IPv4/IPv6 function.

Begin listening for incoming connections. A connection must be accepted with the accept() function before they can be used. Each time a connection request is accepted is frees up another slot in the pending queue.

Parameters
addrThe address from which to accept connections. If you want to accept connections from anywhere pass in the value INADDR_ANY.
portThe port number to listen on.
maxpendThe maximum number of pending connection requests allowed for this listen socket. If not specified, the default is 5.
Returns
TCP Socket Status
int32_t fdListen = listen(INADDR_ANY, 1234, 5);
See also
accept4(), accept6(), listen6(), close()

◆ listen6()

int listen6 ( const IPADDR6 addr,
uint16_t  port,
uint8_t  maxpend = 5 
)

Listen for incoming IPv6 connections.

Calling listen() in dual stack mode will automatically select the correct IPv4/IPv6 function.

Begin listening for incoming connections. A connection must be accepted with the accept() function before they can be used. Each time a connection request is accepted is frees up another slot in the pending queue.

Parameters
&addrThe address from which to accept connections. If you want to accept connections from anywhere pass in the value INADDR_ANY.
portThe port number to listen on.
maxpendThe maximum number of pending connection requests allowed for this listen socket. If not specified, the default is 5.
Returns
TCP Socket Status
int32_t fdListen = listen(INADDR_ANY, 1234, 5);
See also
accept4(), accept6(), listen4(), close()

◆ NoBlockConnect4()

int NoBlockConnect4 ( IPADDR4  ipAddress,
uint16_t  remotePort,
IPADDR4  interfaceIpAddress = IPADDR4::NullIP() 
)
inline

Create a file descriptior and return immediately, does not wait for connection to complete. Before attempting to use the socket verify a connection was successful with TcpGetSocketState(fd).

Calling NoBlockConnect() in dual stack mode will automatically select the correct IPv4/IPv6 function.

By default it will use the fist network interface.

Parameters
ipAddressIP address of the remote host.
remotePortPort number of the remote host.
timeoutNumber of system Time Ticks to wait. A value of 0 waits forever.
interfaceIpAddressOptional parameter to specify which local network interface to use for the connection. The default is 0, which is the first network interface in the configuration.
Returns
A file descriptor to be used if the connection is successful, which will occur at a later time. Verify the connection state before using with TcpGetSocketState().
See also
NoBlockConnect6(), TcpGetSocketState()

◆ NoBlockConnect6()

int NoBlockConnect6 ( const IPADDR6 ipAddress,
uint16_t  remotePort,
const IPADDR6 interfaceIpAddress 
)
inline

Create a file descriptior and return immediately, does not wait for connection to complete. Before attempting to use the socket verify a connection was successful with TcpGetSocketState(fd).

Calling NoBlockConnect() in dual stack mode will automatically select the correct IPv4/IPv6 function.

By default it will use the fist network interface.

Parameters
ipAddressIP address of the remote host.
remotePortPort number of the remote host.
timeoutNumber of system Time Ticks to wait. A value of 0 waits forever.
interfaceIpAddressOptional parameter to specify which local network interface to use for the connection. The default is 0, which is the first network interface in the configuration.
Returns
A file descriptor to be used if the connection is successful, which will occur at a later time. Verify the connection state before using with TcpGetSocketState().
See also
NoBlockConnect4(), TcpGetSocketState()

◆ setsockoption()

int setsockoption ( int  fd,
int  option 
)

Set TCP socket options.

Parameters
fdSocket file descriptor.
optionSocket option to set: TCP Socket Options.
Returns
A bitmask of the options for the specified socket.
See also
clrsockoption(), getsockoption(), setsocketackbuffers(), SetSocketRxBuffers(), SetSocketTxBuffers()

◆ SocketPeek()

char SocketPeek ( int  fd)

Returns the next char that would be read, 0 if no data.

Parameters
fdSocket file descriptor.
Returns
The next char that would be read.

◆ TcpGetLastRxInterval()

uint32_t TcpGetLastRxInterval ( int  fd)

Returns the number of system Time Ticks since the last packet was received. This is the difference between the current system time and lastRxTime of the socket.

Parameters
fdThe socket file descriptor.
Returns
The number of system Time Ticks since the last packet was received on the connection.
See also
TcpGetLastRxTime()

◆ TcpGetLastRxTime()

uint32_t TcpGetLastRxTime ( int  fd)

Returns the value of system Time Ticks when the last packet was received. Used for the TCP Keep Alive feature.

Each TCP connection has a corresponding Socket_struct. One of the elements of this struct is a variable called lastRxTime, which stores the current system time tick every time a packet is received. This function enables you to find out when the last packet was received by returning LastRxTime.

This function is used in conjuntion with TcpSendKeepAlive() to implement the TCP keepalive feature.

  • If lastRxTime is the same before and after a keepalive packet is sent, the client has not responded to the keepalive packet and it can be assumed that connection is lost.
  • Make sure to allow enough time for the client to respond to the keep alive packet before checking the time.
  • Do not call TcpGetLastRxTime() more often than once every second.
Parameters
fdThe socket file descriptor.
Returns
The value of system Time Ticks when the last packet was received on the connection.
See also
TcpSendKeepAlive()

◆ TcpGetSocketInterface()

int TcpGetSocketInterface ( int  fd)

Return the network interface asociated with a TCP socket.

Parameters
fdSocket file descriptor.
Returns
The network interface number (undefined for listening sockets)

◆ TcpGetSocketState()

uint8_t TcpGetSocketState ( int  fd)

Return the current state of a TCP socket.

Parameters
fdSocket file descriptor.
Returns
The current state of the socket: TCP Socket State

◆ TcpSendKeepAlive()

void TcpSendKeepAlive ( int  fd)

Send a TCP keep alive packet to a remote host.

Sends an empty packet with a decremented sequence number to a remote host. The sequence number will be one less than the last time a packet was sent. The remote host will respond with a TCP acknowledgment (ACK). This function is used in conjuntion with TcpGetLastRxTime() to implement the TCP keepalive feature.

Parameters
fdThe socket file descriptor.
See also
TcpGetLastRxTime()