The WriteLine method writes a line of text to the server
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 lpszBuffer 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 value returned in the
lpnLength parameter will typically be larger than the original
string length (reflecting the additional CR and LF characters), unless
the string was already terminated with CRLF.
There are some limitations when using WriteLine. This
method should only be used to send text, never binary data. In
particular, it will discard nulls and append linefeed and carriage
return control characters to the data stream. The Unicode version of
this method will accept a Unicode string, however it does not support
writing raw Unicode data to the socket. Unicode strings will be
automatically converted to UTF-8 encoding using the
WideCharToMultiByte function and then written to the socket as
a stream of bytes.
This method will force the thread to block until the complete line
of text has been written, the write operation times out or the server
aborts the connection. If this method is called with
asynchronous events enabled, it will automatically switch the socket
into a blocking mode, send the data and then restore the socket to
asynchronous operation. If another socket operation is attempted
while WriteLine is blocked sending data to the server, an
error will occur. It is recommended that this method only be used
with blocking (synchronous) socket connections; if the application
needs to establish multiple simultaneous connections, it should
create worker threads to manage each connection.
The Write and WriteLine methods can be safely
intermixed.
Unlike the Write function, it is possible for data to have
been written to the socket if the return value is zero. For example,
if a timeout occurs while the method is waiting to send more data to
the server, it will return zero; however, some data may have
already been written prior to the error condition. If this is the
case, the lpnLength argument will specify the number of
characters actually written up to that point.