BOOL ReadLine(
	SOCKET hSocket,
	LPTSTR lpszBuffer,
	LPINT lpnLength
);

BOOL ReadLine(
	LPTSTR lpszBuffer,
	LPINT lpnLength
);

BOOL ReadLine(
	SOCKET hSocket,
	CString& strBuffer,
	INT nMaxLength
);

BOOL ReadLine(
	CString& strBuffer,
	INT nMaxLength
);

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

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

Pointer to the string buffer that will contain the data when the method returns. The string will be terminated with a null character, and will not contain the end-of-line characters. An alternate form of the method accepts a CString argument which will contain the line of text returned by the server.

lpnLength

A pointer to an integer value which specifies the length of the buffer. The value should be initialized to the maximum number of characters that can be copied into the string buffer, including the terminating null character. When the method returns, its value will updated with the actual length of the string.

nMaxLength

An integer value which specifies the maximum length of the buffer.

Return Value

If the method succeeds, the return value is non-zero. If the method fails, the return value is zero. To get extended error information, call GetLastError.

Remarks

The ReadLine method reads data from the socket and copies into a specified string buffer. Unlike the Read method which reads arbitrary bytes of data, this method is specifically designed to return a single line of text data in a string. When an end-of-line character sequence is encountered, the method will stop and return the data up to that point. The string buffer is guaranteed to be null-terminated and will not contain the end-of-line 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.

There are some limitations when using ReadLine. The method should only be used to read text, never binary data. In particular, the method will discard nulls, linefeed and carriage return control characters. The Unicode version of this method will return a Unicode string, however it does not support reading raw Unicode data from the socket. Any data read from the socket is internally buffered as octets (eight-bit bytes) and converted to Unicode using the MultiByteToWideChar function.

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

Unlike the Read method, it is possible for data to be returned in the string buffer even if the return value is zero. Applications should check the length of the string 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 return value.

Example

CString strBuffer;
BOOL bResult;

do
{
    bResult = pServer->ReadLine(strBuffer);

    if (strBuffer.GetLength() > 0)
    {
        // Process the line of data returned in the string
        // buffer; the string is always null-terminated
    }
} while (bResult);

DWORD dwError = pServer->GetLastError();

if (dwError == ST_ERROR_CONNECTION_CLOSED)
{
    // The remote host has closed its side of the connection and
    // there is no more data available to be read
}
else if (dwError != 0)
{
    // An error has occurred while reading a line of data
}

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

IsReadable, Peek, Read, ReadStream, Write, WriteLine, WriteStream

Copyright © 2023 Catalyst Development Corporation. All rights reserved.