int ConnectToTCPServerEx (unsigned int *conversationHandle, unsigned int serverPort, char *serverHostName, tcpFuncPtr clientCallbackFunction, void *callbackData, unsigned int timeout, unsigned int clientPort);
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.
![]() |
Note You are strongly encouraged to let the library select a default port by passing TCP_ANY_LOCAL_PORT. If you want to specify a particular client port, you must make sure that it is available and reserved for use by your application to avoid conflicting with other TCP connections using that port. |
Input | ||||
Name | Type | Description | ||
serverPort | 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_DISCONNECTReceived 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_DATAREADYReceived 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.
|
||
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.
|
||
clientPort | unsigned integer | The port number to use for the client on the localhost. | ||
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. |
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, |