User API

TCP Socket functions and communication flow. More...

typedef uint32_t(*	netTCP_cb_t) (int32_t socket, netTCP_Event event, const NET_ADDR *addr, const uint8_t *buf, uint32_t len)
	TCP Event callback function.
int32_t	netTCP_GetSocket (netTCP_cb_t cb_func)
	Allocate a free TCP socket. [thread-safe].
netStatus	netTCP_ReleaseSocket (int32_t socket)
	Release TCP socket and free resources. [thread-safe].
netStatus	netTCP_Listen (int32_t socket, uint16_t port)
	Open TCP socket for incoming connection. [thread-safe].
netStatus	netTCP_Connect (int32_t socket, const NET_ADDR *addr, uint16_t local_port)
	Initiate a TCP connection to a remote node. [thread-safe].
netStatus	netTCP_Close (int32_t socket)
	Stop TCP communication and start closing procedure. [thread-safe].
netStatus	netTCP_Abort (int32_t socket)
	Instantly stop TCP communication. [thread-safe].
uint32_t	netTCP_GetMaxSegmentSize (int32_t socket)
	Determine maximum number of data bytes that can be sent in TCP packet. [thread-safe].
uint8_t *	netTCP_GetBuffer (uint32_t size)
	Allocate memory for TCP send buffer. [thread-safe].
bool	netTCP_SendReady (int32_t socket)
	Check if TCP socket can send data. [thread-safe].
netStatus	netTCP_Send (int32_t socket, uint8_t *buf, uint32_t len)
	Send a data packet to remote node. [thread-safe].
netTCP_State	netTCP_GetState (int32_t socket)
	Determine current state of a TCP socket. [thread-safe].
netStatus	netTCP_ResetReceiveWindow (int32_t socket)
	Reset TCP window size to a default value from the configuration. [thread-safe].
netStatus	netTCP_SetOption (int32_t socket, netTCP_Option option, uint32_t val)
	Set TCP socket IP option. [thread-safe].
uint16_t	netTCP_GetLocalPort (int32_t socket)
	Retrieve local port number of TCP socket. [thread-safe].
netStatus	netTCP_GetPeer (int32_t socket, NET_ADDR *addr, uint32_t addr_len)
	Retrieve IP address and port number of remote peer. [thread-safe].
uint32_t	netTCP_GetTimer (int32_t socket)
	Determine TCP socket connection timeout. [thread-safe].

Description

TCP Socket functions and communication flow.

TCP operations can be divided into three distinct phases (SYN, SYN-ACK, ACK). All connections must be properly established in this three-step handshake process before any data can be transfered. After the data transfer has finished, the connection termination closes established sockets and releases all allocated resources. The basic communication flow using TCP sockets is shown in this picture:

Flow Diagram for TCP Sockets Communication

Connection Establishment

For establishing a connection, TCP uses a three-way handshake. Before a client can connect to a server, the server must first open a socket for incoming connections (using netTCP_Listen): this is called a passive open. Once the passive open is established, a client may initiate an active open. To establish a connection, the three-way handshake takes place:

1. The active open is performed by the client sending a SYN to the server (using netTCP_Connect).
2. In response, the server replies with an ACK and an own SYN.
3. Finally, the client sends an ACK back to the server.

At this point, a full-duplex communication is established.

Connection Termination

The connection can be terminated from each side independently. When an endpoint wishes to stop the connection (by calling netTCP_Close), it transmits a FIN packet, which the other end acknowledges with an ACK. Therefore, a typical connection close requires a pair of FIN and ACK segments from each TCP endpoint and takes some time. After both FIN/ACK exchanges are concluded, the side that sent the first FIN before receiving one waits for a timeout before finally closing the connection, during which time the local port is unavailable for new connections; this prevents confusion due to delayed packets being delivered during subsequent connections.

Operation Modes

The TCP Socket API distinguishes two operation modes: Server and Client. Both modes have distinct functions that can either be used in the respective mode only or are available for multiple operation modes.

TCP Server Mode

The function netTCP_Listen opens a TCP socket on a local port for any incoming connection and starts TCP Server Mode. The next free socket can be allocated using the function netTCP_GetSocket. This function requires a callback function to be present that is called by the Network Core whenever a TCP event occurs. The TCP Server callback function is inside the module TCP_Socket_Server.c. To add the module to your project, simply right-click on the Source group, select Add New Item to Group, then click on User Code Template and scroll in the template files list until you find the TCP Socket Server template. Customize this module to the application's needs.

It is not allowed to call netTCP_Listen with a port number of 0, because this is a reserved port number. To determine the state of a TCP socket, use netTCP_GetState. The user application can monitor the progress when establishing or closing a connection with this function.

As soon as a client requests to connect, the socket/port combination is used for the data transfer. For that, the function netTCP_GetMaxSegmentSize helps to determine the maximum number of data bytes that can be sent in a TCP packet. Call this function after the remote client is connected. To retrieve information about the client that is connected to the server, use netTCP_GetPeer which returns the IP address and port of the connected remote client.

For the data transmission, the functions netTCP_GetBuffer, netTCP_SendReady, and netTCP_Send are used. The first one allocates memory for the TCP send buffer. The second one checks if the TCP socket is free for sending data, while the third one does the actual transmission.

To instantly stop TCP communication (even during data transmission), use netTCP_Abort. Use this only for cases, where the transmission really needs to be aborted. Normally, TCP communication will be stopped using netTCP_Close. In server mode, this does not close the socket, but only ends the active client connection. To fully close the listener socket as well, call netTCP_Close a second time. In that case, call netTCP_ReleaseSocket as well, as this function finally frees the memory used by the TCP socket.

Code Example

#include "rl_net.h"
 
// Notify the user application about TCP socket events.
uint32_t tcp_cb_func (int32_t socket, netTCP_Event event,
                      const NET_ADDR *addr, const uint8_t *buf, uint32_t len) {
 
  switch (event) {
    case netTCP_EventConnect:
      // Connect request received in server mode
      if (addr->addr_type == NET_ADDR_IP4) {
        // IPv4 client
        if (addr->addr[0] == 192  &&
            addr->addr[1] == 168  &&
            addr->addr[2] == 0    &&
            addr->addr[3] == 1) {
          // Accept connection from client at 192.168.0.1
          return (1);
        }
      }
      else {
        // IPv6 client
        const uint8_t ip6_addr[NET_ADDR_IP6_LEN] = { 
                         0xfe, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
                         0x1c, 0x30, 0x6c, 0xff, 0xfe, 0xa2, 0x45, 0x5e };
        if (memcmp (addr->addr, ip6_addr, NET_ADDR_IP6_LEN) == 0) {
          // Accept connection from client at [fe80::1c30:6cff:fea2:455e]
          return (1);
        }
      }
      // Deny connection.
      return (0);
 
    case netTCP_EventEstablished:
      // Connection established
      break;
 
    case netTCP_EventClosed:
      // Connection was properly closed
      break;
 
    case netTCP_EventAborted:
      // Connection is for some reason aborted
      break;
 
    case netTCP_EventACK:
      // Previously sent data acknowledged
      break;
 
    case netTCP_EventData:
      // Data received
      if ((buf[0] == 0x01) && (len == 2)) {
        // Switch LEDs on and off
        // LED_out (buf[1]);
      }
      break;
  }
  return (0);
}
 
// Allocate and initialize the socket.
int main (void) {
  int32_t tcp_sock;
 
  netInitialize ();
 
  // Initialize TCP Socket and start listening on port 2000
  tcp_sock = netTCP_GetSocket (tcp_cb_func);
  if (tcp_sock >= 0) {
    netTCP_Listen (tcp_sock, 2000);
  }
}

TCP Client Mode

The function netTCP_Connect initiates a connection to a remote TCP server and starts TCP Client Mode. You need to specify the socket number, the IP address and port of the remote machine and the local port.

If netTCP_Connect is called with a local port number of 0, the Network Core determines which port to use. Later, this information can be retrieved using the function netTCP_GetLocalPort. To determine the state of a TCP socket, use netTCP_GetState. The user application can monitor the progress when establishing or closing a connection with this function.

As soon as a client requests to connect, the socket/port combination is used for the data transfer. For that, the function netTCP_GetMaxSegmentSize helps to determine the maximum number of data bytes that can be sent in a TCP packet. Call this function after the client is connected to remote server.

Sending Data

To be able to successfully send data via TCP, you first need to request a buffer to be allocated using netTCP_GetBuffer. Then, fill the buffer with the data to be sent and send it using netTCP_Send. The buffer will be released by the Network Component automatically. If the buffer is not valid (not allocated with the netTCP_GetBuffer function), the buffer is ignored.

The Network Component does not send 0-length packets. So it is possible to release a buffer that has been allocated, by simply calling netTCP_Send with parameter len = 0.

The user code template TCP_Socket_Client.c contains an exemplary send function, called send_data. The send_data function must be implemented as a state machine. It opens an active TCP connection, sends data, and closes the TCP connection at the end. To add the template to your project, simply right-click on the Source group, select Add New Item to Group, then click on User Code Template and scroll in the template files list until you find the TCP Socket Client template. Adapt the send_data function to your application's needs.

Stopping TCP Communication

To instantly stop TCP communication (even during data transmission), use netTCP_Abort. Use this only for cases, where the transmission really needs to be aborted. In client mode, TCP communication will be stopped using netTCP_Close. The TCP socket will be closed. Subsequently, call netTCP_ReleaseSocket as well, as this function finally frees the memory used by the TCP socket.

Code Example

#include "rl_net.h"
 
int32_t tcp_sock;                       // TCP socket handle
 
// Notify the user application about TCP socket events.
uint32_t tcp_cb_client (int32_t socket, netTCP_Event event,
                        const NET_ADDR *addr, const uint8_t *buf, uint32_t len) {
 
  switch (event) {
    case netTCP_EventConnect:
      // Connect request received in server mode
      break;
 
    case netTCP_EventEstablished:
      // Connection established
      break;
 
    case netTCP_EventClosed:
      // Connection was properly closed
      break;
 
    case netTCP_EventAborted:
      // Connection is for some reason aborted
      break;
 
    case netTCP_EventACK:
      // Previously sent data acknowledged
      break;
 
    case netTCP_EventData:
      // Data received
      break;
  }
  return (0);
}
 
// Connect to TCP server and send data.
void send_data (void) {
  // IPv4 address: 192.168.0.1
  NET_ADDR addr = { NET_ADDR_IP4, 2000,
                    192, 168, 0, 1 };
  // IPv6 address: [fe80::1c30:6cff:fea2:455e]
  //NET_ADDR addr = { NET_ADDR_IP6, 2000,
  //                  0xfe, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  //                  0x1c, 0x30, 0x6c, 0xff, 0xfe, 0xa2, 0x45, 0x5e };
 
  if (tcp_sock >= 0) {
    switch (netTCP_GetState (tcp_sock)) {
      case netTCP_StateUNUSED:
      case netTCP_StateCLOSED:
        // Connect to TCP socket server on port 2000
        netTCP_Connect (tcp_sock, &addr, 0);
        break;
 
      case netTCP_StateESTABLISHED:
        // Connected, send the data
        if (netTCP_SendReady (tcp_sock) == true) {
          uint8_t *sendbuf;
 
          sendbuf = netTCP_GetBuffer (2);
          sendbuf[0] = 0x01;
          sendbuf[1] = 0x55;
 
          netTCP_Send (tcp_sock, sendbuf, 2);
        }
        break;
 
      default:
        break;
    }
  }
}
 
// Allocate and initialize the socket.
int main (void) {
 
  netInitialize ();
 
  // Allocate a free TCP socket.
  tcp_sock = netTCP_GetSocket (tcp_cb_client);
}

Typedef Documentation

netTCP_cb_t

uint32_t(* netTCP_cb_t)(int32_t socket, netTCP_Event event, const NET_ADDR *addr, const uint8_t *buf, uint32_t len)

TCP Event callback function.

Parameters

[in]	socket	TCP socket handle.
[in]	event	Event type as shown in the table below (netTCP_Event).
[in]	addr	Pointer to the structure containing the remote IP address and port number.
[in]	buf	Pointer to buffer containing the received data.
[in]	len	Number of bytes in the received packet.

Returns

Integer Value used to decide whether to accept or reject an incoming connection (see details).

• 1 - incoming connection accepted.
• 0 - incoming connection rejected.

Is the type definition for the TCP callback function. The Network Core calls the callback function whenever a TCP event occurs.

The argument socket is the TCP socket handle of the local machine.

The argument addr is a pointer to the buffer containing the IP address and port of the remote machine.

The argument event specifies the type of event that occurred as shown in the table below or netTCP_Event.

The argument buf points to a buffer containing the received data.

The argument len specifies the number of received data bytes.

The Network Core uses the return value of the callback function only when the event is netTCP_EventConnect. It uses the return value to decide whether to accept or reject an incoming connection when the TCP socket is listening. If the listener function returns 1, then it accepts the incoming connection. If the listener function returns 0, it rejects the incoming connection. Thus, you can define the listener function to selectively reject incoming connections from particular IP addresses.

Event Type	Description
netTCP_EventConnect	A Connect Request has been received from a remote client that wants to connect to the server
netTCP_EventEstablished	The TCP socket has connected to the remote machine
netTCP_EventClosed	The TCP connection has been properly closed
netTCP_EventAbort	The TCP connection has been aborted
netTCP_EventACK	Acknowledgment has been received from the remote host for the previously sent data
netTCP_EventData	A TCP data packet has been received

Parameter for:

• netTCP_GetSocket

Code Example TCP Client

uint32_t tcp_cb_func (int32_t socket, netTCP_Event event,
                      const NET_ADDR *addr, const uint8_t *buf, uint32_t len) {
 
  switch (event) {
    case netTCP_EventConnect:
      // Connect request received in server mode
      break;
 
    case netTCP_EventEstablished:
      // Connection established
      break;
 
    case netTCP_EventClosed:
      // Connection was properly closed
      break;
 
    case netTCP_EventAborted:
      // Connection is for some reason aborted
      break;
 
    case netTCP_EventACK:
      // Previously sent data acknowledged
      break;
 
    case netTCP_EventData:
      // Data received
      break;
  }
  return (0);
}

Code Example TCP Server

uint32_t tcp_cb_func (int32_t socket, netTCP_Event event,
                      const NET_ADDR *addr, const uint8_t *buf, uint32_t len) {
 
  switch (event) {
    case netTCP_EventConnect:
      // Connect request received in server mode
      if (addr->addr_type == NET_ADDR_IP4) {
        // IPv4 client
        if (addr->addr[0] == 192  &&
            addr->addr[1] == 168  &&
            addr->addr[2] == 0    &&
            addr->addr[3] == 1) {
          // Accept connection from client at 192.168.0.1
          return (1);
        }
      }
      else {
        // IPv6 client
        const uint8_t ip6_addr[NET_ADDR_IP6_LEN] = { 
                         0xfe, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
                         0x1c, 0x30, 0x6c, 0xff, 0xfe, 0xa2, 0x45, 0x5e };
        if (memcmp (addr->addr, ip6_addr, NET_ADDR_IP6_LEN) == 0) {
          // Accept connection from client at [fe80::1c30:6cff:fea2:455e]
          return (1);
        }
      }
      // Deny connection.
      return (0);
 
    case netTCP_EventEstablished:
      // Connection established
      break;
 
    case netTCP_EventClosed:
      // Connection was properly closed
      break;
 
    case netTCP_EventAborted:
      // Connection is for some reason aborted
      break;
 
    case netTCP_EventACK:
      // Previously sent data acknowledged
      break;
 
    case netTCP_EventData:
      // Data received
      if ((buf[0] == 0x01) && (len == 2)) {
        // Switch LEDs on and off
        // LED_SetOut (buf[1]);
      }
      break;
  }
  return (0);
}

Function Documentation

netTCP_Abort()

netStatus netTCP_Abort

(

int32_t

socket

)

Instantly stop TCP communication. [thread-safe].

Parameters

[in]

socket

socket handle obtained with netTCP_GetSocket.

Returns

status code that indicates the execution status of the function.

The function netTCP_Abort closes the TCP connection immediately by sending a TCP frame with the RESET flag set to the remote machine.

The argument socket specifies the handle of the socket.

The Network Core calls the listener callback function only when a remote peer has aborted the connection. If the aborted socket is initiated locally by calling netTCP_Abort, then the callback function is not called.

Possible netStatus return values:

• netOK: Socket aborted successfully.
• netInvalidParameter: Invalid socket requested.
• netWrongState: Socket in invalid state.

Note

After calling netTCP_Abort you cannot use the socket to send or receive any data. The socket remains allocated until you release it.

Code Example (see netTCP_ReleaseSocket)

netTCP_Close()

netStatus netTCP_Close

(

int32_t

socket

)

Stop TCP communication and start closing procedure. [thread-safe].

Parameters

[in]

socket

socket handle obtained with netTCP_GetSocket.

Returns

status code that indicates the execution status of the function.

The function netTCP_Close initiates the procedure to close the TCP connection. It might take some time to close the connection.

The argument socket specifies the socket handle.

The Network Core calls the listener callback function only when a remote peer has closed the connection. If the socket is closed locally by calling netTCP_Close, then the callback function is not called.

When a socket is used in the netTCP_Listen functions, the socket does not close by calling netTCP_Close. Only the active connection is closed, and the socket will be available for new incoming connection. To close such a socket, the function netTCP_Close needs to be called twice.

Possible netStatus return values:

• netOK: Socket closing successfully started.
• netInvalidParameter: Invalid socket requested.
• netWrongState: Socket in invalid state.

Note

After calling netTCP_Close the socket still remains allocated until you release it.

Code Example

netTCP_State state;
 
// This TCP connection is no longer needed
netTCP_Close (tcp_sock);
 
// Wait for the socket to close
for (;;) {
  state = netTCP_GetState (tcp_sock);
  if (state < netTCP_StateLISTEN) {
    break;
  }
  if (state == netTCP_StateLISTEN) [
    // Socket is in server mode, needs additional close request
    netTCP_Close (tcp_sock);
  }
  // Pass control to other threads
  osDelay (10);
}
 
// A socket is in netTCP_StateCLOSED state now
netTCP_ReleaseSocket (tcp_sock);

netTCP_Connect()

netStatus netTCP_Connect	(	int32_t	socket,
		const NET_ADDR *	addr,
		uint16_t	local_port
	)

Initiate a TCP connection to a remote node. [thread-safe].

Parameters

[in]	socket	socket handle obtained with netTCP_GetSocket.
[in]	addr	structure containing remote IP address and port.
[in]	local_port	local port number. 0 = system assigned local port.

Returns

status code that indicates the execution status of the function.

The function netTCP_Connect initiates a connection to a remote server.

The argument socket is a socket handle on the local machine for communicating.

The argument addr points to the buffer containing the IP address and port of the remote socket server.

The argument local_port specifies the port on the local machine. If local_port is set to 0, then the Network Core allocates the first free TCP port automatically. If you need the port number later, use netTCP_GetLocalPort to retrieve this information.

Possible netStatus return values:

• netOK: Connection initiated successfully.
• netInvalidParameter: Invalid parameter provided.
• netWrongState: Socket not closed.

Code Example IPv4

// IPv4 address: 192.168.0.1
NET_ADDR4 addr = { NET_ADDR_IP4, 2000, 192, 168, 0, 1 };
 
netTCP_Connect (tcp_sock, (NET_ADDR *)&addr, 0);
 
// Wait for the socket to connect 
for (;;) {
  switch (netTCP_GetState (tcp_sock)) {
    case netTCP_StateUNUSED:
    case netTCP_StateCLOSED:
      // Failed to connect to TCP socket server
      return;
 
    case netTCP_StateESTABLISHED:
      // Connected, socket is ready to send data
      break;
  }
  // Pass control to other threads
  osDelay (10);
}

Code Example IPv6

// IPv6 address: [fe80::1c30:6cff:fea2:455e]
NET_ADDR addr = { NET_ADDR_IP6, 2000,
                  0xfe, 0x80, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
                  0x1c, 0x30, 0x6c, 0xff, 0xfe, 0xa2, 0x45, 0x5e };
 
netTCP_Connect (tcp_sock, &addr, 0);
 
// Wait for the socket to connect 
for (;;) {
  switch (netTCP_GetState (tcp_sock)) {
    case netTCP_StateUNUSED:
    case netTCP_StateCLOSED:
      // Failed to connect to TCP socket server
      return;
 
    case netTCP_StateESTABLISHED:
      // Connected, socket is ready to send data
      break;
  }
  // Pass control to other threads
  osDelay (10);
}

netTCP_GetBuffer()

uint8_t * netTCP_GetBuffer

(

uint32_t

size

)

Allocate memory for TCP send buffer. [thread-safe].

Parameters

[in]

size

number of bytes to allocate.

Returns

pointer to the allocated memory.

• NULL = out of memory.

The function netTCP_GetBuffer allocates memory for the TCP send buffer into which your application can write the outgoing data packet.

The argument size specifies the number of data bytes that the application wants to send.

After the TCP frame has been sent and an acknowledgment has been received from the remote host, the Network Core automatically de-allocates the memory used by the send buffer in the netTCP_Send function.

A default Maximum Segment Size (MSS) of 1440 bytes is defined at start-up. However, when establishing a connection with a remote machine, the Network Core might negotiate a different (smaller) value for MSS. Use netTCP_GetMaxSegmentSize to check the available MSS for the current connection.

Note

• Your application must call the netTCP_GetBuffer function each time it wants to send a TCP data packet.
• The size of the allocated memory must not exceed the TCP Maximum Segment Size (1440 bytes).
• Writing more data than the allocated size of the data buffer overwrites the Memory Manager Block links and causes the Network Core to crash.

Code Example (see netTCP_Send)

netTCP_GetLocalPort()

uint16_t netTCP_GetLocalPort

(

int32_t

socket

)

Retrieve local port number of TCP socket. [thread-safe].

Parameters

[in]

socket

socket handle obtained with netTCP_GetSocket.

Returns

local port number.

• 0 = socket invalid or in invalid state.

The function netTCP_GetLocalPort returns the local TCP port that is used for a specific socket. This is useful if you have not specified a port in the function netTCP_Connect, as the system sets the port automatically then.

The argument socket specifies the local socket handle that is to be used.

Code Example

int32_t tcp_sock;
 
tcp_sock = netTCP_GetSocket (tcp_cb_func);
if (tcp_sock >= 0) {
  netTCP_Connect (tcp_sock, addr, 0);
  printf ("Local port is %d\n", netTCP_GetLocalPort (tcp_sock));
}

netTCP_GetMaxSegmentSize()

uint32_t netTCP_GetMaxSegmentSize

(

int32_t

socket

)

Determine maximum number of data bytes that can be sent in TCP packet. [thread-safe].

Parameters

[in]

socket

socket handle obtained with netTCP_GetSocket.

Returns

maximum segment size in bytes.

The function netTCP_GetMaxSegmentSize determines the maximum number of bytes that can be sent in the TCP packet (Maximum Segment Size).

The argument socket specifies the handle of the TCP socket.

A default Maximum Segment Size (MSS) of 1440 bytes is defined at start-up. However, when establishing a connection with a remote machine, the Network Core might negotiate a different (smaller) value for MSS.

Note

This function can only be called after establishing a connection using the functions netTCP_Listen or netTCP_Connect.

Code Example (see netTCP_Send)

netTCP_GetPeer()

netStatus netTCP_GetPeer	(	int32_t	socket,
		NET_ADDR *	addr,
		uint32_t	addr_len
	)

Retrieve IP address and port number of remote peer. [thread-safe].

Parameters

[in]	socket	socket handle obtained with netTCP_GetSocket.
[out]	addr	structure that will receive IP address and port number.
[in]	addr_len	size of NET_ADDR structure for remote peer.

Returns

status code that indicates the execution status of the function.

The function netTCP_GetPeer provides the IP address and port of the remote client that is connected.

The argument socket specifies the local socket handle that is to be used.

The argument addr points to the buffer where the IP address and port of the remote machine will be stored.

The argument addr_len specifies the length of the addr structure. The Network Core checks the length, if the library can store the IP address of the remote peer into the structure. The IP address contains an IPv4 or IPv6 address.

Possible netStatus return values:

• netOK: Operation completed successfully.
• netInvalidParameter: Invalid parameter provided.
• netWrongState: Socket connection not established.

Code Example

NET_ADDR peer;
char ip_ascii[40];
 
netTCP_GetPeer (tcp_sock, &peer, sizeof(peer));
netIP_ntoa (peer.addr_type, peer.addr, ip_ascii, sizeof (ip_ascii));
printf ("Peer address: %s\n", ip_ascii);
printf ("Peer port: %d\n", peer.port);

netTCP_GetSocket()

int32_t netTCP_GetSocket

(

netTCP_cb_t

cb_func

)

Allocate a free TCP socket. [thread-safe].

Parameters

[in]

cb_func

event listening callback function.

Returns

socket handle number or execution status:

• value >= 0: socket handle number.
• value < 0: error occurred, -value is execution status as defined with netStatus.

The function netTCP_GetSocket allocates a free TCP socket. The function initializes all the state variables of the TCP socket to the default state.

The argument cb_func is the event callback function of the TCP socket. The Network Core calls this function whenever a TCP event occurs. Refer to netTCP_cb_t.

Possible netStatus return values:

• netInvalidParameter: Callback function not valid.
• netError: No free sockets available.

Note

• You must call the netTCP_GetSocket function before any other function calls to the TCP socket.
• You must define the listener function to use with the TCP socket.

Code Example

int32_t tcp_sock;
 
uint32_t tcp_cb_func (int32_t socket, netTCP_Event event,
                      const NET_ADDR *addr, const uint8_t *buf, uint32_t len) {
   .. 
  return (0);
}
 
// Allocate a free TCP socket
tcp_sock = netTCP_GetSocket (tcp_cb_func);
if (tcp_sock < 0) {
  printf ("Get socket failed.\n");
}

netTCP_GetState()

netTCP_State netTCP_GetState

(

int32_t

socket

)

Determine current state of a TCP socket. [thread-safe].

Parameters

[in]

socket

socket handle obtained with netTCP_GetSocket.

Returns

state information as defined with netTCP_State.

The function netTCP_GetState determines the current state of the TCP socket. The application can monitor the progress when establishing or closing a connection with this function. The most useful state values are netTCP_StateCLOSED, netTCP_StateLISTEN, and netTCP_StateESTABLISHED.

The argument socket specifies the socket handle.

The netTCP_GetState function returns the current state of the TCP socket:

State	Description
netTCP_StateINVALID	Socket is not available (not in the range of sockets specified in the NET_Config_TCP.h file).
netTCP_StateUNUSED	Socket is free and not allocated yet. The function cannot return this value.
netTCP_StateCLOSED	Socket is allocated to an application but the connection is closed.
netTCP_StateLISTEN	Socket is listening for incoming connections.
netTCP_StateSYN_RECEIVED	Socket has received a TCP packet with the flag SYN set.
netTCP_StateSYN_SENT	Socket has sent a TCP packet with the flag SYN set.
netTCP_StateFIN_WAIT_1	Socket has sent a FIN packet, to start the closing of the connection.
netTCP_StateFIN_WAIT_2	Socket has received acknowledgment from the remote machine for the FIN packet it sent out from the local machine. Socket is now waiting for a FIN packet from the remote machine.
netTCP_StateCLOSING	Socket has received a FIN packet from the remote machine independently
netTCP_StateLAST_ACK	Socket is waiting for the last ACK packet to the FIN packet it sent out.
netTCP_StateTIME_WAIT	Socket is waiting on a 2 MSS timeout before closing the connection.
netTCP_StateESTABLISHED	Socket has established a TCP connection. You can transfer data only in this state.

Code Example (see netTCP_Connect)

netTCP_GetTimer()

uint32_t netTCP_GetTimer

(

int32_t

socket

)

Determine TCP socket connection timeout. [thread-safe].

Parameters

[in]

socket

socket handle obtained with netTCP_GetSocket.

Returns

connection timeout timer in seconds.

• 0 = socket invalid or in invalid state.

The function netTCP_GetTimer returns the timer value of a time out or the current keep alive value. When the time out expires, the Network Core will either close the socket, or send a keep-alive frame.

The argument socket specifies the local socket handle that is to be used.

Code Example

printf ("Socket %d will close in %d seconds\n", socket, netTCP_GetTimer (socket));

netTCP_Listen()

netStatus netTCP_Listen	(	int32_t	socket,
		uint16_t	port
	)

Open TCP socket for incoming connection. [thread-safe].

Parameters

[in]	socket	socket handle obtained with netTCP_GetSocket.
[in]	port	local port number.

Returns

status code that indicates the execution status of the function.

The function netTCP_Listen opens a socket for incoming connections by causing the socket to listen at a local TCP port.

The argument socket specifies the socket handle to listen on the local machine.

The argument port specifies the TCP port number to listen at. If the argument port is 0, the function returns error, because this port is reserved. If you need the port number later, use netTCP_GetLocalPort to retrieve this information.

Possible netStatus return values:

• netOK: Socket opened successfully.
• netInvalidParameter: Invalid parameter provided.
• netWrongState: Socket not closed.

Note

Server applications (such as Telnet and HTTP server) must open a TCP socket for listening.

Code Example

int32_t tcp_sock;
 
// Initialize TCP Socket and start listening on port 2000
tcp_sock = netTCP_GetSocket (tcp_cb_func);
if (tcp_sock >= 0) {
  netTCP_Listen (tcp_sock, 2000);
}
 ..

netTCP_ReleaseSocket()

netStatus netTCP_ReleaseSocket

(

int32_t

socket

)

Release TCP socket and free resources. [thread-safe].

Parameters

[in]

socket

socket handle obtained with netTCP_GetSocket.

Returns

status code that indicates the execution status of the function.

The function netTCP_ReleaseSocket de-allocates the memory used by the TCP socket.

The argument socket specifies the handle of the socket to be released.

Possible netStatus return values:

• netOK: Socket released successfully.
• netInvalidParameter: Invalid socket requested.
• netWrongState: Socket not closed.

Note

• You must call the netTCP_ReleaseSocket function when you do not need the TCP socket any longer.
• After calling netTCP_ReleaseSocket the socket is free to be used by another process.

Code Example

// This TCP connection needs to close immediately
netTCP_Abort (tcp_sock);
// Socket will not be needed any more
netTCP_ReleaseSocket (tcp_sock);

netTCP_ResetReceiveWindow()

netStatus netTCP_ResetReceiveWindow

(

int32_t

socket

)

Reset TCP window size to a default value from the configuration. [thread-safe].

Parameters

[in]

socket

socket handle obtained with netTCP_GetSocket.

Returns

status code that indicates the execution status of the function.

The function netTCP_ResetReceiveWindow resets the TCP window size to a default value defined with TCP_RECEIVE_WIN_SIZE macro in the Net_Config_TCP.h file.

The argument socket specifies the handle of the socket for which to reset the window size.

This function can only be used with sockets that have a TCP flow control enabled. Enable a TCP flow control for the socket by calling the netTCP_SetOption function with the netTCP_OptionFlowControl enabled. This socket option enables using a Sliding Window protocol in receive.

In Flow Control mode, each received data packet reduces the receiving Window Size by the number of data bytes received in the packet. Soon the window size becomes very small or 0. The remote host stops sending data and waits for a window update. As soon as the received data is processed, we can call a netTCP_ResetReceiveWindow function to reopen the receiver window for further incoming data.

Depending on the context from where this function was called, it performs the following actions:

• resets the window size of the socket and returns if called from the callback function. The window size is actually changed in the acknowledge packet generated by the Network Core when the callback function returns.
• resets the window size and sends out a Window Update packet if called from the other part of the user application.
• does nothing if the socket is not in netTCP_StateESTABLISHED state and the netTCP_OptionFlowControl option is not set.

Possible netStatus return values:

• netOK: Receive window reset successfully.
• netInvalidParameter: Invalid socket requested or flow control not enabled.
• netWrongState: Socket connection not established.

Code Example

uint8_t uart_buf[TCP_RECEIVE_WIN_SIZE];
 
uint32_t tcp_cb_func (int32_t socket, netTCP_Event event,
                      const NET_ADDR *addr, const uint8_t *buf, uint32_t len) {
  switch (event) {
    case netTCP_EventConnect:
      // Connect request received in server mode
      return (1);
 
    case netTCP_EventData:
      // Data received
      memcpy (&uart_buf[head], buf, len);
      head += len;
      break;
  }
  return (0);
}
 
int main (void) {
  int32_t tcp_sock;
  uint32_t head, tail;
 
  // Initialize the Network Core
  netInitialize ();
  tcp_sock = netTCP_GetSocket (tcp_cb_func);
  if (tcp_sock >= 0) {
    // Start listening on TCP port 8080 
    netTCP_Listen (tcp_sock, 8080);
  }
 
  // Ethernet to UART bridge
  head = 0;
  tail = 0;
  while (1) {
    if (uart_busy () || head == tail) {
      // UART is busy or buffer is empty, do nothing
      continue;
    }
    // Send a byte to UART
    send_uart (uart_buf[tail++]);
    if (tail == head) {
      // Buffer is empty, all bytes consumed
      tail = 0;
      head = 0;
      netTCP_ResetReceiveWindow (tcp_sock);
    }
  }
}

netTCP_Send()

netStatus netTCP_Send	(	int32_t	socket,
		uint8_t *	buf,
		uint32_t	len
	)

Send a data packet to remote node. [thread-safe].

Parameters

[in]	socket	socket handle obtained with netTCP_GetSocket.
[in]	buf	buffer containing the data.
[in]	len	length of data in bytes.

Returns

status code that indicates the execution status of the function.

The function netTCP_Send sends the data packet to a remote machine.

The argument socket specifies the socket handle to use for communication on the local machine.

The argument buf points to the constructed TCP data packet.

The argument len specifies the number of bytes in the data packet.

If the netTCP_Send fails to send the data, it releases the memory buffer specified with the argument buf and returns with an error status. The function cannot send data if:

• the TCP connection is not established
• previously sent data is not acknowledged from the remote machine.

Possible netStatus return values:

• netOK: Send data successful.
• netInvalidParameter: Invalid or not supported parameter provided.
• netWrongState: Socket not connected or closing.
• netBusy: Previously sent data not acknowledged.
• netError: Send data failed.

Note

• You must allocate the memory using netTCP_GetBuffer before calling netTCP_Send.
• The buffer will be released, no matter if netTCP_Send is successful or not.
• netTCP_Send does not send 0-length packets. It is possible to release a buffer that has been allocated, by simply calling netTCP_Send with parameter len = 0.
• The socket must already be opened and connected for communication.
• It is not allowed to call netTCP_Send from the callback function of the socket.

Code Example

uint8_t *sendbuf;
uint32_t maxlen;
 
if (netTCP_SendReady (tcp_sock)) {
  // The socket is ready to send the data
  maxlen  = netTCP_GetMaxSegmentSize (tcp_sock);
  sendbuf = netTCP_GetBuffer (maxlen);
  memcpy (sendbuf, my_data_buf, maxlen);
  netTCP_Send (tcp_sock, sendbuf, maxlen);
}

netTCP_SendReady()

bool netTCP_SendReady

(

int32_t

socket

)

Check if TCP socket can send data. [thread-safe].

Parameters

[in]

socket

socket handle obtained with netTCP_GetSocket.

Returns

send status:

• true = Ready to send data.
• false = Not ready.

The function netTCP_SendReady determines whether the TCP socket can send data. It does this by checking whether the TCP connection has been established and whether the socket has received an acknowledgment from the remote machine for data sent previously.

The argument socket specifies the socket handle.

Code Example (see netTCP_Send)

netTCP_SetOption()

netStatus netTCP_SetOption	(	int32_t	socket,
		netTCP_Option	option,
		uint32_t	val
	)

Set TCP socket IP option. [thread-safe].

Parameters

[in]	socket	socket handle obtained with netTCP_GetSocket.
[in]	option	option name as defined with netTCP_Option.
[in]	val	option value.

Returns

status code that indicates the execution status of the function.

The function netTCP_SetOption sets different options for a TCP socket identified by the argument socket.

The argument option specifies the TCP option that is to be set (see below).

The argument val carries the value of the TCP option that is to be set.

Option	Description	Value
netTCP_OptionTOS	IPv4 Type of Service	val=TOS
netTCP_OptionTrafficClass	IPv6 Traffic Class	val=TrafficClass
netTCP_OptionTimeout	TCP Idle Timeout	val=timeout (in seconds)
netTCP_OptionKeepAlive	TCP Keep Alive	val: 0=disabled (default), 1=enabled
netTCP_OptionFlowControl	TCP Flow Control	val: 0=disabled (default), 1=enabled
netTCP_OptionDelayedACK	TCP Delayed Acknowledgment	val: 0=disabled (default), 1=enabled

Possible netStatus return values:

• netOK: Option successfully set.
• netInvalidParameter: Invalid parameter provided.
• netWrongState: Requested socket not allocated.

Code Example

int32_t tcp_sock;
 
tcp_sock = netTCP_GetSocket (tcp_cb_func);
if (tcp_sock >= 0) {
  // Set disconnect timeout to 30 seconds
  netTCP_SetOption (tcp_sock, netTCP_OptionTimeout, 30);
  // Enable Keep Alive
  netTCP_SetOption (tcp_sock, netTCP_OptionKeepAlive, 1);
}