WriteLine Method  
 

Send a line of text to the remote host, terminated by a carriage-return and linefeed.

Syntax

object.WriteLine( [Buffer] )

Parameters

Buffer
An optional String value which contains the text that will be sent to the remote host. The data will always be terminated with a carriage-return and linefeed control character sequence. If this argument is omitted, then a only a carriage-return and linefeed are written to the socket.  If the string contains Unicode characters, it will be automatically converted to use standard UTF-8 encoding prior to being sent. If the string contains an embedded null character, any data that follows the null character will be discarded.

Return Value

This method returns True if the contents of the string have been written to the socket. If an error occurs, the method will return False.

Remarks

The WriteLine method writes a line of text to the remote host and terminates the line with a carriage-return and linefeed control character sequence. Unlike the Write method which writes arbitrary bytes of data to the socket, this method is specifically designed to write a single line of text data from a string.

If the Buffer string is terminated with a linefeed (LF) or carriage return (CR) character, it will be automatically converted to a standard CRLF end-of-line sequence. Because the string will be sent with a terminating CRLF sequence, the number of characters sent to the remote host will typically be larger than the original string length (reflecting the additional CR and LF characters), unless the string was already terminated with CRLF.

If the string value passed to the WriteLine method is a Unicode string which contains non-ASCII characters, it will be internally converted to 8-bit ANSI encoded text before being written to the socket. The remote host must be able to recognize the encoding and process it appropriately. The ReadLine method will automatically convert any encoded characters that it reads from the socket back to their original Unicode encoding. The CodePage property can be used to change the default code page used when converting the text.

The WriteLine method should only be used to send text, never binary data. In particular, the function will discard any data that follows a null character and will append linefeed and carriage return control characters to the data stream. Calling this this method will force the thread to block until the complete line of text has been written, the write operation times out or the remote host aborts the connection. If this function is called with the Blocking property set to False, it will automatically switch the socket into a blocking mode, send the data and then restore the socket to non-blocking mode. If another socket operation is attempted while the WriteLine method is blocked sending data to the remote host, an error will occur. It is recommended that this method only be used with blocking socket connections.

The Write and WriteLine function calls can be safely intermixed.

See Also

CodePage Property, IsWritable Property, Timeout Property, Read Method, ReadLine Method, Write Method, WriteStream Method