Jump to main content

##

# 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

Parameters | Description
--- | ---
addType | The type of address being used. Example: IP_ADDRESS_TYPE_IPV4.
remotePort | TCP port to connect to. The local port for client sockets will be automatically picked by the TCP module.
remoteAddress | The 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