1.2.3.1.1 Abstraction Model

This module provides software abstraction of the TCP module existent in any TCP/IP Stack implementation.

How the Library Works

Connections made over TCP guarantee data transfer at the expense of throughput. Connections are made through a three-way handshake process, ensuring a one-to-one connection. Remote nodes advertise how much data they are ready to receive, and all data transmitted must be acknowledged. If a remote node fails to acknowledge the receipt of data, it is automatically retransmitted. This ensures that network errors such as lost, corrupted, or out-of-order packets are automatically corrected.

To accomplish this, TCP must use buffers for both the transmit and receive operations. Once the transmit buffer is full, no more data can be sent until the remote node has acknowledged receipt.

When the Harmony TCP/IP Stack is used without a RTOS, the application must return to the main system loop to allow the other services in the system, including the TCP/IP stack, to advance.

The remote node cannot transmit more data until the local device has acknowledged receipt and receiving space is available in the buffer. When a local application needs to read more data, it must return to the main system/application loop and wait for a new packet to arrive.

Core Functionality

The following diagram provides an overview for the use of the TCP module.

Server sockets are opened using TCPIP_TCP_ServerOpen. This function will open a listening socket_waiting for client connections on the specified TCP port number. A client socket_is opened using TCPIP_TCP_ClientOpen. This function will open a socket_that connects to a remote host. The remote host is specified using an IP address and a TCP port number.

Once connected, applications can read and write data. On each entry, the application must verify that the socket_is still connected. For most applications a call to TCPIP_TCP_IsConnected will be sufficient, but TCPIP_TCP_WasReset may also be used for listening sockets that may turn over quickly.

To write data, call TCPIP_TCP_PutIsReady to check how much space is available. Then, call the TCPIP_TCP_ArrayPut function to write data as space is available. Once complete, call TCPIP_TCP_Flush to transmit data immediately. Alternately, return to the main system/stack loop. Data will be transmitted by the internal TCP state machine as the buffer becomes full or a programmable delay time has passed.

To read data, call TCPIP_TCP_GetIsReady to determine how many bytes are ready to be retrieved. Then use the TCPIP_TCP_ArrayGet function to read data from the_socket, and/or the TCPIP_TCP_Find family of functions to locate data in the buffer. When no more data remains, return to the main system/stack loop to wait for more data to arrive.

If the application needs to close the connection, call TCPIP_TCP_Disconnect, and then return to the main system/stack loop and wait for the remote node to acknowledge the disconnection. Client sockets will be closed and associated resources freed, while listening sockets will wait for a new connection. For more information, refer to the examples provided with the MPLAB Harmony distribution examples, or read the associated RFC.