# ConnectToTCPServer

int ConnectToTCPServer (unsigned int *conversationHandle, unsigned int portNumber, char *serverHostName, tcpFuncPtr clientCallbackFunction, void *callbackData, unsigned int timeout);

## Purpose

Establishes a connection between your program and a TCP server specified by a port number and server host name. Your program becomes a TCP client.

Thereafter, all messages from the server are routed through the specified client callback function.

## Parameters

Input
Name | Type | Description
portNumber | unsigned integer | The port number of the server to which to connect.
serverHostName | string | The name of the host machine for the server. The name can either be an alphabetical string, such as xyz.natinst.com, or a numerical string, such as 123.456.7.8. If you pass NULL or an empty string, the server host is assumed to be the local machine.
clientCallbackFunction | TCP function pointer | Pointer to the synchronous callback function that processes messages that your program receives as a TCP client. The callback function must be of the following form: int (*tcpFuncPtr) (unsigned handle, int xType, int errCode, void *callbackData); handle contains a value that is unique to each client-server connection. xType specifies the type of message the server sends. The client callback function can receive the following transaction types: TCP_DISCONNECT—Received when a server requests the termination of a connection or when a connection terminates because of an error. If the connection terminates because of an error, the errCode parameter contains a negative error code. TCP_DATAREADY—Received when there is data to be read by the client. Your program, acting as the client, calls ClientTCPRead to obtain the data. Note that this event is received again if you do not read all the available data. Use errCode only when the transaction type is TCP_DISCONNECT.
| Note The return value of the callback is ignored. The callback function should be short and should return as soon as possible.
callbackData | void pointer | The name of the function that the TCP Support Library calls to process messages your program receives as a TCP client. callbackData is a 4-byte value the TCP Support Library passes to the callback function each time the library invokes the callback for the same client. You must define the meaning of the callback data. One way to use callbackData is as a pointer to a data object that you need to access in the callback function. By doing this, you can avoid declaring the data object as a global variable. If you do not want to use callbackData, you can pass zero.
timeout | unsigned integer | The number of milliseconds to wait before returning. For instance, if you pass a value of 100, the function returns an error if 100 milliseconds pass without the connection being established. If you pass zero, the function uses a default timeout of 5,000 milliseconds.
| Note The host name lookup (if needed) is performed before starting the timeout countdown. For instance, if you pass a value of 100, and the hostname lookup takes 50 ms, the function might not return for up to 150 ms.
Output
Name | Type | Description
conversationHandle | unsigned integer | The conversation handle that uniquely represents the connection between the server and the client. Note that zero (0) is a valid handle.

## Return Value

Name | Type | Description
status | integer | Return value indicating whether the function was successful. Unless otherwise stated, zero represents successful execution and a negative number represents the error code. You can call the GetTCPSystemErrorString function to obtain a system message that describes the error. The system messages can be more descriptive than the TCP Library error codes. To obtain the correct system error message, you must call GetTCPSystemErrorString immediately after calling the TCP Library function that failed. For functions that read or write data (ClientTCPRead, ClientTCPWrite, ServerTCPRead, ServerTCPWrite), if the function was successful, the return value is the number of bytes transferred. You can have a maximum of 255 concurrent conversations and up to 1,024 connections. If you exceed this limit, -kTCP_TooManyConnections will be returned. You may not be able to open the maximum number of connections allowed by LabWindows/CVI because of limitations imposed by the operating system.