1.2.3.1.16 TCPIP_TCP_ClientOpen Function

C

TCP_SOCKET TCPIP_TCP_ClientOpen(
    IP_ADDRESS_TYPE addType, 
    TCP_PORT remotePort, 
    IP_MULTI_ADDRESS* remoteAddress
);

Description

Provides a unified method for opening TCP client sockets.

Sockets are created at the TCP module initialization, and can be claimed with this function and freed using TCPIP_TCP_Abort or TCPIP_TCP_Close.

Preconditions

TCP is initialized.

Parameters

ParametersDescription
addTypeThe type of address being used. Example: IP_ADDRESS_TYPE_IPV4.
remotePortTCP port to connect to. The local port for client sockets will be automatically picked by the TCP module.
remoteAddressThe remote address to be used. If 0 then the address is unspecified.

Returns

  • INVALID_SOCKET - No sockets of the specified type were available to be opened.

  • TCP_SOCKET handle - Save this handle and use it when calling all other TCP APIs.

Remarks

IP_ADDRESS_TYPE_ANY is not supported (not a valid type for client open)!

If the remoteAddress != 0 (and the address pointed by remoteAddress != 0) then the socket will immediately initiate a connection to the remote host

If the remoteAddress is unspecified, no connection is initiated. Client socket parameters can be set using TCPIP_TCP_Bind, TCPIP_TCP_RemoteBind, etc. calls and then connection initiated by calling TCPIP_TCP_Connect.

Sockets and user threads protection For efficiency reasons, there is NO PROTECTION for each individual API call except to Open and Close sockets! What it means is that:

  • the user application should close all its sockets before issuing a stack/if down command The stack manager takes care of the internally used sockets

  • A socket can NOT be used concurrently from multiple threads! It's ok to pass a socket from one thread to another as long as there's is no access from more than one thread at a time