This filter can read a sequence of characters of variable length from an open socket. The characters are terminated by a sequence, which is specified via inDelimiter.

The value on the inDelimiter input can contain escape sequences.

An escaped string contains escape sequences, which are combinations of the \ (backslash) and another character, which have special meaning. The supported escape sequences are:

• \r - carriage return (ASCII 13)
• \n - new line (ASCII 10)
• \t - tab character (ASCII 9)
• \\ - verbatim backslash \

The inTimeout input specifies the longest possible waiting time, in milliseconds, for the incoming data to be fully received. When no timeout is specified (set to Auto), the execution is blocking. When the filter execution is terminated by timeout condition no data is returned or removed from the input buffer (Nil is returned instead). In such situation the operation can be retried later. When timeout is et to zero the filter performs a single read attempt and returns immediately when no data is available.

Received bytes are interpreted as UTF-8 encoded text and returned on outText output. When received data is not in a valid UTF-8 encoding IoError is raised.

The outEof output can be used to detect whether the peer finished transmission and gracefully closed connection on its side. To enable this inAcceptEof must be set, otherwise connection closing will be treated as erroneous state.

The point in transmission when the other side closes the connection gracefully is known as the end of stream (or End of File - Eof). All TCP/IP reading filters can normally read data remaining in the input buffer even when the connection has been closed, as long as the whole required chunk of data is present in the input buffer. However, the reaction to the attempt to read from the input buffer beyond the end of the stream depends on the inAcceptEof input. When inAcceptEof is set to False the filter will raise IO_Error when required chunk of data cannot be read. When inAcceptEof is set to True the filter execution is terminated, no data is removed from the input buffer, Nil is returned instead of requested data and the outEof output is set to True. In such situation the socket remains valid and subsequent reads will perform similar data read attempts.

This filter can raise IoError when the connection is disruptively broken or when other network-related error occurred.

• Connect inSocket with the output of TcpIp_Connect or TcpIp_Accept.
• Set inDelimiter to define a character sequence that defines end of line. "\r\n" is the typical value of end of line for Windows-based systems.
• Set inTimeout if you want the filter to abort waiting for data after a predefined time.

User manual

For more information about using this filter, please follow the link: Using TCP/IP Communication.

This filter can throw an exception to report error. Read how to deal with errors in Error Handling.

List of possible exceptions:

This filter is available on Basic Complexity Level.

• TcpIp_WriteText – Outputs a string through a connected TCP socket.

• TcpIp_ReadBuffer – Receives a fixed number of bytes from a connected TCP socket.

• TcpIp_ReadAllText – Receives text from a connected socket until the other side closes connection.

• Application Notes: Using TCP IP Communication - document about connecting devices or establishing communication with Aurora Vision Studio.