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.
The Buffer argument specifies the string variable that
the data will be stored in.
The Length argument specifies the maximum number of bytes
to read. If this argument is omitted, then the control will return
up to 4096 characters in the string. If the application
expects that a single line of text will exceed this value, then it
must be explicitly specified.
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.
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.