Implementation of a half-duplex line-oriented Telnet-like connection. More...

#include <tsTextStream.h>

Inheritance diagram for ts::TextStream:

[legend]

Collaboration diagram for ts::TextStream:

[legend]

Public Member Functions
	TextStream (StreamInterface &stream, const std::string &eol=DEFAULT_EOL, const std::string &prompt=std::string())
	Constructor.

bool	debug () const
	Check if debugging is active.

template<class... Args>
void	debug (const UChar *fmt, Args &&... args)
	Report a debug message with a printf-like interface.

void	debug (const UChar *msg)
	Report a debug message.

template<class... Args>
void	debug (const UString &fmt, Args &&... args)
	Report a debug message with a printf-like interface.

void	debug (const UString &msg)
	Report a debug message.

Report *	delegateReport (Report *report)
	Delegate message logging to another report object.

template<class... Args>
void	error (const UChar *fmt, Args &&... args)
	Report an error message with a printf-like interface.

void	error (const UChar *msg)
	Report an error message.

template<class... Args>
void	error (const UString &fmt, Args &&... args)
	Report an error message with a printf-like interface.

void	error (const UString &msg)
	Report an error message.

template<class... Args>
void	fatal (const UChar *fmt, Args &&... args)
	Report a fatal error message with a printf-like interface.

void	fatal (const UChar *msg)
	Report a fatal error message.

template<class... Args>
void	fatal (const UString &fmt, Args &&... args)
	Report a fatal error message with a printf-like interface.

void	fatal (const UString &msg)
	Report a fatal error message.

void	getAndFlush (ByteBlock &data)
	Get currently buffered input data and flush that buffer.

bool	gotErrors () const
	Check if errors (or worse) were reported through this object.

template<class... Args>
void	info (const UChar *fmt, Args &&... args)
	Report an informational message with a printf-like interface.

void	info (const UChar *msg)
	Report an informational message.

template<class... Args>
void	info (const UString &fmt, Args &&... args)
	Report an informational message with a printf-like interface.

void	info (const UString &msg)
	Report an informational message.

template<class... Args>
void	log (int severity, const UChar *fmt, Args &&... args)
	Report a message with an explicit severity and a printf-like interface.

template<class... Args>
void	log (int severity, const UString &fmt, Args &&... args)
	Report a message with an explicit severity and a printf-like interface.

void	log (int severity, const UString &msg)
	Report a message with an explicit severity.

int	maxSeverity () const
	Get maximum severity level.

void	raiseMaxSeverity (int level)
	Raise maximum severity level.

bool	readLine (std::string &line, const AbortInterface *abort=nullptr)
	Receive a line.

bool	readLine (UString &line, const AbortInterface *abort=nullptr)
	Receive a line.

bool	readText (std::string &data, const AbortInterface *abort=nullptr)
	Receive character data.

bool	readText (UString &data, const AbortInterface *abort=nullptr)
	Receive character data.

UString	reportPrefix () const
	Get the current prefix to display.

void	reset ()
	Reset the internal buffer.

void	resetErrors ()
	Reset the error indicator.

void	setEOL (const std::string &eol)
	Set a new end-of-line sequence for output lines.

void	setMaxSeverity (int level)
	Set maximum severity level.

void	setReportPrefix (const UString &prefix)
	Set the prefix to display before each message.

template<class... Args>
void	severe (const UChar *fmt, Args &&... args)
	Report a severe error message with a printf-like interface.

void	severe (const UChar *msg)
	Report a severe error message.

template<class... Args>
void	severe (const UString &fmt, Args &&... args)
	Report a severe error message with a printf-like interface.

void	severe (const UString &msg)
	Report a severe error message.

StreamInterface &	stream ()
	Get a reference to the associated stream device.

bool	verbose () const
	Check if verbose reporting is active.

template<class... Args>
void	verbose (const UChar *fmt, Args &&... args)
	Report a verbose message with a printf-like interface.

void	verbose (const UChar *msg)
	Report a verbose message.

template<class... Args>
void	verbose (const UString &fmt, Args &&... args)
	Report a verbose message with a printf-like interface.

void	verbose (const UString &msg)
	Report a verbose message.

bool	waitForPrompt (const AbortInterface *abort=nullptr)
	Receive a prompt.

template<class... Args>
void	warning (const UChar *fmt, Args &&... args)
	Report a warning message with a printf-like interface.

void	warning (const UChar *msg)
	Report a warning error message.

template<class... Args>
void	warning (const UString &fmt, Args &&... args)
	Report a warning message with a printf-like interface.

void	warning (const UString &msg)
	Report a warning error message.

bool	writeLine (const std::string &str)
	Send a text line to the server.

bool	writeLine (const UString &str)
	Send a text line to the server.

bool	writeText (const std::string &str)
	Send a string to the server.

bool	writeText (const UString &str)
	Send a string to the server.

Static Public Attributes
static const std::string	DEFAULT_EOL
	Default end-of-line sequence (CR-LF).

Protected Member Functions
virtual void	writeLog (int severity, const UString &msg) override
	Actual message reporting method.

Detailed Description

Implementation of a half-duplex line-oriented Telnet-like connection.

This class supports the communication with a half-duplex line-oriented Telnet-like server:

The server sends a prompt.
The client sends a request.
The server replies by one or more lines followed by the prompt.

From the client point of view the interface must allow:

To send a request.
To get replies line until all the lines of the replies have been read.

This class is also a subclass of Report, allowing it to be used to send log messages.

Although this class is typically used on a TCPConnection (or a subclass of it), it can be used on any class implementing StreamInterface. It the underlying device is not interactive (a file for instance), don't try to use a prompt of course.

Constructor & Destructor Documentation

◆ TextStream()

ts::TextStream::TextStream	(	StreamInterface &	stream,
		const std::string &	eol = `DEFAULT_EOL`,
		const std::string &	prompt = `std::string()`
	)

explicit

Constructor.

Parameters

[in,out]	stream	Associated stream device. The device object must remain valid as long as this object is valid.
[in]	eol	End-of-file sequence to send at end of each line. Input is auto-adaptive: a line is always read up to a LF character and all previous CR characters are discarded.
[in]	prompt	Prompt string to send to the client.

Member Function Documentation

◆ setEOL()

void ts::TextStream::setEOL ( const std::string & eol )

inline

Set a new end-of-line sequence for output lines.

Input is auto-adaptive: a line is always read up to a LF character and all previous CR characters are discarded.

Parameters

[in] eol End-of-file sequence to send at end of each line.

◆ stream()

StreamInterface & ts::TextStream::stream ( )

inline

Get a reference to the associated stream device.

Returns: A reference to the associated stream device.

◆ reset()

void ts::TextStream::reset ( )

inline

Reset the internal buffer.

If the underlying stream device is reused for several connections or session, reset() should be called each time a new connection is established. Otherwise, the new connection would reuse unread bytes from the previous connection.

Note that if the stream device is a TCPConnection or a subclass of it, the reset is automatically performed when the socket connects or disconnects.

◆ writeText() [1/2]

bool ts::TextStream::writeText ( const std::string & str )

Send a string to the server.

Parameters

[in] str The string to writeText to the server.

Returns: True on success, false on error.

◆ writeText() [2/2]

bool ts::TextStream::writeText ( const UString & str )

Send a string to the server.

Parameters

[in] str The string to writeText to the server.

Returns: True on success, false on error.

◆ writeLine() [1/2]

bool ts::TextStream::writeLine ( const std::string & str )

Send a text line to the server.

Parameters

[in] str The line to send to the server.

Returns: True on success, false on error.

◆ writeLine() [2/2]

bool ts::TextStream::writeLine ( const UString & str )

Send a text line to the server.

Parameters

[in] str The line to send to the server.

Returns: True on success, false on error.

◆ readText() [1/2]

bool ts::TextStream::readText	(	std::string &	data,
		const AbortInterface *	abort = `nullptr`
	)

Receive character data.

Parameters

[out]	data	The received data.
[in]	abort	If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).

Returns: True on success, false on error. Return true until the last line of the replies has been received.

◆ readText() [2/2]

bool ts::TextStream::readText	(	UString &	data,
		const AbortInterface *	abort = `nullptr`
	)

Receive character data.

Parameters

[out]	data	The received data.
[in]	abort	If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).

Returns: True on success, false on error. Return true until the last line of the replies has been received.

◆ readLine() [1/2]

bool ts::TextStream::readLine	(	std::string &	line,
		const AbortInterface *	abort = `nullptr`
	)

Receive a line.

Parameters

[out]	line	The received line.
[in]	abort	If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).

Returns: True on success, false on error. Return true until the last line of the replies has been received.

◆ readLine() [2/2]

bool ts::TextStream::readLine	(	UString &	line,
		const AbortInterface *	abort = `nullptr`
	)

Receive a line.

Parameters

[out]	line	The received line.
[in]	abort	If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).

Returns: True on success, false on error. Return true until the last line of the replies has been received.

◆ waitForPrompt()

bool ts::TextStream::waitForPrompt ( const AbortInterface * abort = nullptr )

Receive a prompt.

Do not wait if the prompt is empty.

Parameters

[in] abort If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).

Returns: True on success, false on error.

◆ getAndFlush()

void ts::TextStream::getAndFlush ( ByteBlock & data )

Get currently buffered input data and flush that buffer.

This method is useful when TCP connection switches from text mode (Telnet protocol) to binary mode. The returned data are the start of the input binary data. The remaining data can be received using methods from the parent class TCPConnection.

Parameters

[out] data Currently buffered data.

◆ writeLog()

virtual void ts::TextStream::writeLog	(	int	severity,
		const UString &	msg
	)

overrideprotectedvirtual

Actual message reporting method.

The method is called only when a message passed the severity filter. It is not necessary to recheck the maximum severity inside the method. By default, does nothing.

Parameters

[in]	severity	Message severity.
[in]	msg	Message text.

Reimplemented from ts::Report.

◆ setMaxSeverity()

void ts::Report::setMaxSeverity ( int level )

inherited

Set maximum severity level.

Messages with higher severities are not reported.

Parameters

[in] level Set report to that level.

◆ raiseMaxSeverity()

void ts::Report::raiseMaxSeverity ( int level )

inherited

Raise maximum severity level.

The severity can only be increased (more verbose, more debug), never decreased.

Parameters

[in] level Set report at least to that level.

◆ maxSeverity()

int ts::Report::maxSeverity ( ) const

inlineinherited

Get maximum severity level.

Returns: Current maximum debug level.

◆ gotErrors()

bool ts::Report::gotErrors ( ) const

inlineinherited

Check if errors (or worse) were reported through this object.

Errors which were reported through delegated reports are ignored.

Returns: True if errors (or worse) were reported through this object.

◆ resetErrors()

void ts::Report::resetErrors ( )

inlineinherited

Reset the error indicator.

See also: gotErrors()

◆ setReportPrefix()

void ts::Report::setReportPrefix ( const UString & prefix )

inlineinherited

Set the prefix to display before each message.

Parameters

[in] prefix The prefix to prepend to all messages.

◆ reportPrefix()

UString ts::Report::reportPrefix ( ) const

inlineinherited

Get the current prefix to display.

Returns: The current prefix to display.

◆ delegateReport()

Report * ts::Report::delegateReport ( Report * report )

inherited

Delegate message logging to another report object.

Parameters

[in] report New report object to which messages are delegated. Use nullptr to remove the delegation and return to normal logging.

Returns: Previous delegate report, return a null pointer if there was no previous delegate.

◆ debug() [1/5]

bool ts::Report::debug ( ) const

inlineinherited

Check if debugging is active.

Returns: True if current reporting level is Debug or higher.

◆ debug() [2/5]

void ts::Report::debug ( const UChar * msg )

inlineinherited

Report a debug message.

Parameters

[in] msg Message line.

◆ debug() [3/5]

void ts::Report::debug ( const UString & msg )

inlineinherited

Report a debug message.

Parameters

[in] msg Message line.

◆ debug() [4/5]

template<class... Args>

void ts::Report::debug	(	const UChar *	fmt,
		Args &&...	args
	)

inlineinherited

Report a debug message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ debug() [5/5]

template<class... Args>

void ts::Report::debug	(	const UString &	fmt,
		Args &&...	args
	)

inlineinherited

Report a debug message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ verbose() [1/5]

bool ts::Report::verbose ( ) const

inlineinherited

Check if verbose reporting is active.

Returns: True if current reporting level is Verbose or higher.

◆ verbose() [2/5]

void ts::Report::verbose ( const UChar * msg )

inlineinherited

Report a verbose message.

Parameters

[in] msg Message line.

◆ verbose() [3/5]

void ts::Report::verbose ( const UString & msg )

inlineinherited

Report a verbose message.

Parameters

[in] msg Message line.

◆ verbose() [4/5]

template<class... Args>

void ts::Report::verbose	(	const UChar *	fmt,
		Args &&...	args
	)

inlineinherited

Report a verbose message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ verbose() [5/5]

template<class... Args>

void ts::Report::verbose	(	const UString &	fmt,
		Args &&...	args
	)

inlineinherited

Report a verbose message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ log() [1/3]

void ts::Report::log	(	int	severity,
		const UString &	msg
	)

inherited

Report a message with an explicit severity.

Parameters

[in]	severity	Message severity.
[in]	msg	Message line.

◆ log() [2/3]

template<class... Args>

void ts::Report::log	(	int	severity,
		const UChar *	fmt,
		Args &&...	args
	)

inlineinherited

Report a message with an explicit severity and a printf-like interface.

Parameters

[in]	severity	Message severity.
[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ log() [3/3]

template<class... Args>

void ts::Report::log	(	int	severity,
		const UString &	fmt,
		Args &&...	args
	)

inlineinherited

Report a message with an explicit severity and a printf-like interface.

Parameters

[in]	severity	Message severity.
[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ fatal() [1/4]

void ts::Report::fatal ( const UChar * msg )

inlineinherited

Report a fatal error message.

Parameters

[in] msg Message line.

◆ fatal() [2/4]

void ts::Report::fatal ( const UString & msg )

inlineinherited

Report a fatal error message.

Parameters

[in] msg Message line.

◆ fatal() [3/4]

template<class... Args>

void ts::Report::fatal	(	const UChar *	fmt,
		Args &&...	args
	)

inlineinherited

Report a fatal error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ fatal() [4/4]

template<class... Args>

void ts::Report::fatal	(	const UString &	fmt,
		Args &&...	args
	)

inlineinherited

Report a fatal error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ severe() [1/4]

void ts::Report::severe ( const UChar * msg )

inlineinherited

Report a severe error message.

Parameters

[in] msg Message line.

◆ severe() [2/4]

void ts::Report::severe ( const UString & msg )

inlineinherited

Report a severe error message.

Parameters

[in] msg Message line.

◆ severe() [3/4]

template<class... Args>

void ts::Report::severe	(	const UChar *	fmt,
		Args &&...	args
	)

inlineinherited

Report a severe error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ severe() [4/4]

template<class... Args>

void ts::Report::severe	(	const UString &	fmt,
		Args &&...	args
	)

inlineinherited

Report a severe error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ error() [1/4]

void ts::Report::error ( const UChar * msg )

inlineinherited

Report an error message.

Parameters

[in] msg Message line.

◆ error() [2/4]

void ts::Report::error ( const UString & msg )

inlineinherited

Report an error message.

Parameters

[in] msg Message line.

◆ error() [3/4]

template<class... Args>

void ts::Report::error	(	const UChar *	fmt,
		Args &&...	args
	)

inlineinherited

Report an error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ error() [4/4]

template<class... Args>

void ts::Report::error	(	const UString &	fmt,
		Args &&...	args
	)

inlineinherited

Report an error message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ warning() [1/4]

void ts::Report::warning ( const UChar * msg )

inlineinherited

Report a warning error message.

Parameters

[in] msg Message line.

◆ warning() [2/4]

void ts::Report::warning ( const UString & msg )

inlineinherited

Report a warning error message.

Parameters

[in] msg Message line.

◆ warning() [3/4]

template<class... Args>

void ts::Report::warning	(	const UChar *	fmt,
		Args &&...	args
	)

inlineinherited

Report a warning message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ warning() [4/4]

template<class... Args>

void ts::Report::warning	(	const UString &	fmt,
		Args &&...	args
	)

inlineinherited

Report a warning message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ info() [1/4]

void ts::Report::info ( const UChar * msg )

inlineinherited

Report an informational message.

Parameters

[in] msg Message line.

◆ info() [2/4]

void ts::Report::info ( const UString & msg )

inlineinherited

Report an informational message.

Parameters

[in] msg Message line.

◆ info() [3/4]

template<class... Args>

void ts::Report::info	(	const UChar *	fmt,
		Args &&...	args
	)

inlineinherited

Report an informational message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

◆ info() [4/4]

template<class... Args>

void ts::Report::info	(	const UString &	fmt,
		Args &&...	args
	)

inlineinherited

Report an informational message with a printf-like interface.

Parameters

[in]	fmt	Format string with embedded '%' sequences.
[in]	args	List of arguments to substitute in the format string.

See also: UString::format()

Member Data Documentation

◆ DEFAULT_EOL

const std::string ts::TextStream::DEFAULT_EOL

static

Default end-of-line sequence (CR-LF).

The Telnet protocol defines CR-LF as end-of-line sequence.

The documentation for this class was generated from the following file:

tsTextStream.h

Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ TextStream()

Member Function Documentation

◆ setEOL()

◆ stream()

◆ reset()

◆ writeText() [1/2]

◆ writeText() [2/2]

◆ writeLine() [1/2]

◆ writeLine() [2/2]

◆ readText() [1/2]

◆ readText() [2/2]

◆ readLine() [1/2]

◆ readLine() [2/2]

◆ waitForPrompt()

◆ getAndFlush()

◆ writeLog()

◆ setMaxSeverity()

◆ raiseMaxSeverity()

◆ maxSeverity()

◆ gotErrors()

◆ resetErrors()

◆ setReportPrefix()

◆ reportPrefix()

◆ delegateReport()

◆ debug() [1/5]

◆ debug() [2/5]

◆ debug() [3/5]

◆ debug() [4/5]

◆ debug() [5/5]

◆ verbose() [1/5]

◆ verbose() [2/5]

◆ verbose() [3/5]

◆ verbose() [4/5]

◆ verbose() [5/5]

◆ log() [1/3]

◆ log() [2/3]

◆ log() [3/3]

◆ fatal() [1/4]

◆ fatal() [2/4]

◆ fatal() [3/4]

◆ fatal() [4/4]

◆ severe() [1/4]

◆ severe() [2/4]

◆ severe() [3/4]

◆ severe() [4/4]

◆ error() [1/4]

◆ error() [2/4]

◆ error() [3/4]

◆ error() [4/4]

◆ warning() [1/4]

◆ warning() [2/4]

◆ warning() [3/4]

◆ warning() [4/4]

◆ info() [1/4]

◆ info() [2/4]

◆ info() [3/4]

◆ info() [4/4]

Member Data Documentation

◆ DEFAULT_EOL