ReadLine Method  
 

Read up to a line of data from the socket and returns it in a string buffer.

Syntax

object.ReadLine( Buffer, [Length] )

Parameters

Buffer
A buffer that the data will be stored in. If the variable is a String then the data will be returned as a string of characters. If the data returned by the server contains UTF-8 encoded text, it will automatically be converted to standard UTF-16 Unicode text. If you wish to read the data without conversion, provide a Byte array as the buffer. This parameter must be passed by reference.
Length
A numeric value which specifies the number of bytes to read. Its maximum value is 231-1 = 2147483647. This argument is required to be present for string data. If a value is specified for this argument for other permissible types of data, and it is less than number of bytes that is determined by the control, then Length will override the internally computed value. If the argument is omitted, then the maximum number of bytes to read is determined by the size of the buffer.

Return Value

This method will return True if a line of data has been read. If an error occurs or there is no more data available to read, then the method will return False. It is possible for data to be returned in the string buffer even if the return value is False. Applications should check the length of the string after the method returns to determine if any data was copied into the buffer. For example, if a timeout occurs while the method is waiting for more data to arrive on the socket, it will return zero; however, data may have already been copied into the string buffer prior to the error condition. It is the responsibility of the application to process that data, regardless of the function return value.

Remarks

The ReadLine method reads data from the socket up to the specified number of bytes or until an end-of-line character sequence is encountered. Unlike the Read method which reads arbitrary bytes of data, this function is specifically designed to return a single line of text data in a string variable. When an end-of-line character sequence is encountered, the function will stop and return the data up to that point; the string will not contain the carriage-return or linefeed characters.

If multi-byte 8-bit encoded characters are read from the socket, by default they will automatically be converted to Unicode according to the value of the CodePage property and returned in the string buffer provided. To prevent the text from being converted to Unicode, call the Read method and use a byte array instead of a string variable.

There are some limitations when using the ReadLine method. The method should only be used to read text, never binary data. In particular, it will discard nulls, linefeed and carriage return control characters. This method will force the thread to block until an end-of-line character sequence is processed, the read operation times out or the remote host closes its end of the socket connection. If the Blocking property is set to False, calling this method will automatically switch the socket into a blocking mode, read the data and then restore the socket to non-blocking mode. If another socket operation is attempted while ReadLine is blocked waiting for data from the remote host, an error will occur. It is recommended that this method only be used with blocking socket connections.

The Read and ReadLine methods can be intermixed, however be aware that the Read method will consume any data that has already been buffered by the ReadLine method and this may have unexpected results.

See Also

CodePage Property, IsReadable Property, Read Method, ReadStream Method, StoreStream Method, Write Method, WriteLine Method