Back to Adaptive Vision Library website

You are here: Start » Function Reference » System » TCP IP » TcpIp_Connect

TcpIp_Connect


Header: STD.h
Namespace: avl
Module: FoundationLite

Connects as a client to a remote TCP server socket.

Syntax

void avl::TcpIp_Connect
(
	TcpIpConnectState& ioState,
	const atl::String& inHost,
	int inPort,
	const atl::Optional<int>& inTimeout,
	const atl::Optional<int>& inKeepAliveTime,
	bool inNoSendDelay,
	atl::Conditional<avl::SocketId>& outSocket
)

Parameters

Name Type Range Default Description
ioState TcpIpConnectState& Object used to maintain state of the function.
inHost const String& \"localhost\" The hostname or IP address to connect to.
inPort int 7 - 65535 12345 TCP port of host to connect to.
inTimeout const Optional<int>& 500 - NIL Timeout in milliseconds, block if not specified.
inKeepAliveTime const Optional<int>& 2000 - NIL When specified activates Tcp/Ip keep alive on new socket with given idle time.
inNoSendDelay bool False Disables the Nagle algorithm for the socket to send the outgoing packets without a delay.
outSocket Conditional<SocketId>& Connected socket ID.

Description

This filter connects to a listening TCP/IP socket.

The inTimeout input specifies the longest possible waiting time, in milliseconds, for the connection to be accepted. When no timeout is specified (set to Auto), the execution is blocking. When filter execution is terminated by timeout condition no socket is returned (Nil is returned on outSocket output) and the operation can be retried later. When remote host can not be found or when remote host is not listening on specified port the connection attempt is repeated until timeout expires. This filter can block for significantly longer than the timeout specified because its work is not cancelled in the middle of a single connection attempt.

Every socket created and returned by this filter must be explicitly closed with TcpIp_Close filter when it is not needed any more.

inKeepAliveTime can be used to enable Keep-Alive mechanism on newly established connection with the host.

Keep-Alive is a mechanism built in the TCP/IP stack, that can be helpful with detecting broken connection in systems with long communication idle periods or with communication in one direction only. When enabled, operating system will send additional control packets to check state of the connection. inKeepAliveTime input specifies the time, in milliseconds, of connection idle state after which connection state will be checked. The exact time after which connection broken state will be detected is system dependent.

The inHost parameter can be entered as a DNS host name or IP address. The time necessary to connect can vary, for example subsequent connections to the same host may be faster because of cached DNS information.

In case of failure for reasons other than timeout, IoError is raised.

Hints

  • Set inHost to an IP address or an url of the server you want to connect to.
  • Set inPort to the same port number that the other side of communication will be listening on.
  • Set inTimeout if you want the filter to abort trying to connect after a predefined time.

See Also

  • TcpIp_Accept – Accepts a connection from a remote client.
  • TcpIp_Close – Close a connected TCP socket gracefully.