ClientTCPRead

int ClientTCPRead (unsigned int conversationHandle, void *dataBuffer, unsigned int dataSize, unsigned int timeout);

Purpose

Allows your program, acting as a TCP client, to request data from the server.

The function waits until some data is available at the port, or until the specified interval expires.

Note   If the function call is successful the return value is the number of bytes read. It is possible that TCP is not able to read all the data in one call. If necessary, you can check the number of bytes read and call this function repeatedly to read the rest of the data as shown in the following example.

Example

char * buffer;
int messageSize;
int bytesToRead;
int bytesRead;

/* Find messageSize and allocate buffer appropriately... */

bytesToRead = messageSize;

while (bytesToRead > 0)

{

bytesRead = ClientTCPRead (connectionHandle, &buffer[messageSize - bytesToRead], bytesToRead, 0);

bytesToRead -= bytesRead;

}

Parameters

Input
Name Type Description
conversationHandle unsigned integer The conversation handle that uniquely represents the connection between the server and the client.
dataBuffer void pointer The pointer to the buffer in which to store the data. NULL is not allowed.
dataSize unsigned integer Maximum number of bytes to read.

dataSize must be less than or equal to the size of dataBuffer.
timeout unsigned integer The number of milliseconds that ClientTCPRead waits for data to be available on the connection. The function returns before the timeout period expires if a portion of the data could be read or written to the port or an error occurs.

If you pass a value of zero, the function uses a default timeout of 5,000 milliseconds.

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.