The SshReadLine function reads data sent by the remote
host and copies it into a specified string buffer. Unlike the
SshRead function which reads arbitrary bytes of data, this
function is specifically designed to return a single line of text
data in a null-terminated string. When an end-of-line character
sequence is encountered, the function 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.
There are some limitations when using SshReadLine. The
function should only be used to read text, never binary data. In
particular, the function will discard nulls, linefeed and carriage
return control characters. The Unicode version of this function
will return a Unicode string, however this function does not
support reading raw Unicode data from the remote host. The data is
internally buffered as octets (eight-bit bytes) and converted to
Unicode using the MultiByteToWideChar function.
This function 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 connection. If
this function is called with asynchronous events enabled, it will
automatically switch the client into a blocking mode, read the data
and then restore the client to asynchronous operation. If another
client operation is attempted while SshReadLine is blocked
waiting for data from the remote host, an error will occur. It is
recommended that this function only be used with blocking
(synchronous) client connections; if the application needs to
establish multiple simultaneous connections, it should create
worker threads to manage each connection.
The SshRead and SshReadLine function calls can be
intermixed, however be aware that SshRead will consume any
data that has already been buffered by the SshReadLine
function and this may have unexpected results.
Unlike the SshRead function, it is possible for data to
be returned in the buffer even if the return value is zero.
Applications should also check the value of the lpnLength
argument to determine if any data was copied into the buffer. For
example, if a timeout occurs while the function is waiting for more
data to arrive, 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.
TCHAR szBuffer[MAXBUFLEN];
INT nLength;
BOOL bResult;
do
{
nLength = sizeof(szBuffer);
bResult = SshReadLine(hSocket, szBuffer, &nLength);
if (nLength > 0)
{
// Process the line of data returned in the string
// buffer; the string is always null-terminated
}
} while (bResult);
DWORD dwError = SshGetLastError();
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
}