Network Dual-Stack Component  Version 7.0 (Beta)
MDK-Professional Middleware for IP Networking
 All Data Structures Files Functions Enumerations Groups Pages
User API

TCP Socket functions and communication flow. More...

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:

tcp_communication_flow.png
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 TCP_Socket_Server.c

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. 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 Client callback function is inside the module TCP_Socket_Client.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 Client template. Customize this module to the application's needs.

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.

The template file TCP_Socket_Client.c also 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. Adapt this function to your application's needs.

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 TCP_Socket_Client.c