| |
| BOOL WriteLine( |
| |
SOCKET hSocket, |
|
| |
LPCTSTR lpszBuffer, |
|
| |
LPINT lpnLength |
|
| ); |
| BOOL WriteLine( |
| |
LPCTSTR lpszBuffer, |
|
| |
LPINT lpnLength |
|
| ); |
Write a line of data to the client, terminated with a
carriage-return and linefeed.
Parameters
- hSocket
- An optional parameter that specifies the handle to the client socket.
If this parameter is omitted, the socket handle for the active
client session will be used. If this method is called outside of a
server event handler, the socket handle must be specified.
- lpszBuffer
- The pointer to a string buffer which contains
the data that will be sent to the remote host. All characters up
to, but not including, the terminating null character will be written to
the socket. The data will always be terminated with a
carriage-return and linefeed control character sequence. If this
parameter points to an empty string or NULL pointer, then a only a
carriage-return and linefeed are written to the socket.
- lpnLength
- A pointer to an integer value which will contain the number of
characters written to the socket, including the carriage-return and
linefeed sequence. If this information is not required, a NULL
pointer may be specified.
Return Value
If the function succeeds, the return value is non-zero. If the
function fails, the return value is zero. To get extended error
information, call GetLastError.
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, the WriteLine
method is
specifically designed to write a single line of text data from a
null-terminated string. This method will force the session thread to
block until the complete line of text has been written, the write
operation times out or the remote host aborts the connection.
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.
The Write and WriteLine methods can be safely
intermixed.
Unlike the Write method, 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 remote host, 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.
Requirements
Minimum Desktop Platform: Windows 7 (Service Pack 1)
Minimum Server Platform: Windows Server 2008 R2 (Service Pack 1)
Header: Include cswsock10.h
Import Library: cswskv10.lib
Unicode: Implemented as Unicode and ANSI versions.
See Also
IsWritable,
Read, ReadLine,
ReadStream, Write,
WriteStream
|
|