Start » Filter Reference » System » TCP IP » TcpIp_ReadObject

TcpIp_ReadObject

Basic

Module: FoundationLite

Receives an object through a connected TCP socket.

Name Type Range Description
Input value
 inSocket SocketId Connected socket ID.
Input value
 inTimeout Integer* 100 - Timeout in milliseconds, block if not specified.
Input value
 inAcceptEof Bool When false, throws an IoError on attempt to read data from beyond the end of stream; when true interrupts operation without exception in such a case.
Output value
 outObject <T>? Received object, or Nil if the operation was interrupted (by timeout or reading beyond the end of stream).
Output value
 outEof Bool Indicates whether the operation was interrupted on attempt to get data from beyond the end of stream.

Description

This filter allows reading arbitrary Aurora Vision environment objects from a connected socket.

The data which is expected, should be sent by an Aurora Vision Studio or Aurora Vision Executor process executing TcpIp_WriteObject filter of the same type.

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.

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.

Remarks

User manual

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

Parallel execution

This filter cannot be placed in multiple Workers.

Errors

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

List of possible exceptions:

Error type Description
IoError Type mismatch of serialized object in TcpIp_ReadObject.
Type of serialized object received through TcpIp stream is different than the type of expected object or stream format is incorrect.

Complexity Level

This filter is available on Basic Complexity Level.

Disabled in Lite Edition

This filter is disabled in Lite Edition. It is available only in full, Aurora Vision Studio Professional version.

See Also