Interface class to read/write raw data from/to a stream. More...

#include <tsStreamInterface.h>

Inheritance diagram for ts::StreamInterface:

[legend]

Public Member Functions
virtual bool	asyncCompletedStream (NonBlockingDevice::IOSB *iosb)=0
	Update the status of an asynchronous readStream() or writeStream() after it completed.

virtual bool	endOfStream ()=0
	Check if the end of stream was reached while reading.

virtual bool	isReadStream ()=0
	Check if the stream is open for read.

virtual bool	isWriteStream ()=0
	Check if the stream is open for write.

virtual bool	readStream (void addr, size_t max_size, size_t &ret_size, const AbortInterface abort=nullptr, NonBlockingDevice::IOSB *iosb=nullptr)=0
	Read some data from the stream.

virtual bool	readStream (void addr, size_t size, const AbortInterface abort=nullptr)=0
	Read complete data from the stream.

virtual bool	writeStream (const void addr, size_t size, NonBlockingDevice::IOSB iosb=nullptr)=0
	Write data to the stream.

virtual bool	writeStream (const void addr, size_t size, size_t &written_size, NonBlockingDevice::IOSB iosb=nullptr)=0
	Write some data to the stream.

Static Protected Member Functions
template<class T > requires std::derived_from<T, StreamInterface>
static bool	ReadStreamHelper (T obj, void addr, size_t size, const AbortInterface *abort)
	Implementation helper for fixed-size version of readStream().

template<class T > requires std::derived_from<T, StreamInterface>
static bool	WriteStreamHelper (T obj, const void addr, size_t size, NonBlockingDevice::IOSB *iosb)
	Implementation helper for fixed-size version of writeStream().

Detailed Description

Interface class to read/write raw data from/to a stream.

Member Function Documentation

◆ writeStream() [1/2]

virtual bool ts::StreamInterface::writeStream	(	const void *	addr,
		size_t	size,
		size_t &	written_size,
		NonBlockingDevice::IOSB *	iosb = `nullptr`
	)

pure virtual

Write some data to the stream.

All bytes are written to the stream, blocking or retrying when necessary when the stream is in blocking mode. Return the number of actually written bytes if some error occurred before writing everything.

Parameters

[in]	addr	Address of the data to write.
[in]	size	Size in bytes of the data to write.
[out]	written_size	Actually written size in bytes. Can be less than size in case of error in the middle of the write.
[in,out]	iosb	Address of an IOSB structure. If non-null, the stream must be in non-blocking mode. When null, the stream must be in blocking mode (the default). See the description of ts::NonBlockingDevice::IOSB. Important: The parameter iosb should not be used by applications. It should be used only by "reactive classes", which work in combination with a Reactor.

Returns: True on success, false on error. In case of non-blocking mode, if the I/O is successfully started but still pending, iosb->pending is set to true and the method returns true.

Implemented in ts::TCPConnection, ts::BinaryFile, ts::ForkPipe, and ts::TLSConnection.

◆ writeStream() [2/2]

virtual bool ts::StreamInterface::writeStream	(	const void *	addr,
		size_t	size,
		NonBlockingDevice::IOSB *	iosb = `nullptr`
	)

pure virtual

Write data to the stream.

All bytes are written to the stream, blocking or retrying when necessary when the stream is in blocking mode. The base implementation of writeStream() uses the virtual version with a written_size output parameter.

Parameters

[in]	addr	Address of the data to write.
[in]	size	Size in bytes of the data to write.
[in,out]	iosb	Address of an IOSB structure. If non-null, the stream must be in non-blocking mode. When null, the stream must be in blocking mode (the default). See the description of ts::NonBlockingDevice::IOSB. Important: The parameter iosb should not be used by applications. It should be used only by "reactive classes", which work in combination with a Reactor.

Returns: True on success, false on error or it less than size bytes could be written. In case of non-blocking mode, if the I/O is successfully started but still pending, iosb->pending is set to true and the method returns true.

Implemented in ts::TCPConnection, ts::BinaryFile, ts::ForkPipe, and ts::TLSConnection.

◆ readStream() [1/2]

virtual bool ts::StreamInterface::readStream	(	void *	addr,
		size_t	max_size,
		size_t &	ret_size,
		const AbortInterface *	abort = `nullptr`,
		NonBlockingDevice::IOSB *	iosb = `nullptr`
	)

pure virtual

Read some data from the stream.

Wait and read at least one byte. Don't try to read exactly max_size bytes. If ret_size is less than max_bytes, it is possible to read more.

Parameters

[out]	addr	Address of the buffer for the incoming data.
[in]	max_size	Maximum size in bytes of the buffer.
[out]	ret_size	Returned input size in bytes. If zero, end of file has been reached or an error occurred.
[in]	abort	If non-zero, invoked when I/O is interrupted (in case of user-interrupt, return, otherwise retry).
[in,out]	iosb	Address of an IOSB structure. If non-null, the stream must be in non-blocking mode. When null, the stream must be in blocking mode (the default). See the description of ts::NonBlockingDevice::IOSB. Important: The parameter iosb should not be used by applications. It should be used only by "reactive classes", which work in combination with a Reactor.

Returns: True on success, false on error. In case of non-blocking mode, if the I/O is successfully started but still pending, iosb->pending is set to true and the method returns true.

Implemented in ts::TCPConnection, ts::BinaryFile, ts::ForkPipe, and ts::TLSConnection.

◆ readStream() [2/2]

virtual bool ts::StreamInterface::readStream	(	void *	addr,
		size_t	size,
		const AbortInterface *	abort = `nullptr`
	)

pure virtual

Read complete data from the stream.

Read exactly size bytes, waiting if necessary.

Synchronization: There is no iosb parameter because this method uses blocking I/O by design. An error is returned if the instance of the class which implements StreamInterface is in non-blocking mode.

Parameters

[out]	addr	Address of the buffer for the incoming data.
[in]	size	Size in bytes of the buffer.
[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 or it less than size bytes could be read.

Implemented in ts::TCPConnection, ts::BinaryFile, ts::ForkPipe, and ts::TLSConnection.

◆ asyncCompletedStream()

virtual bool ts::StreamInterface::asyncCompletedStream ( NonBlockingDevice::IOSB * iosb )

pure virtual

Update the status of an asynchronous readStream() or writeStream() after it completed.

This method applies to asynchronous I/O only (Windows), not non-blocking I/O (UNIX).

Parameters

[in,out] iosb Address of the IOSB structure which was used when readStream() or writeStream() was called.

Returns: True on success, false on error.

Implemented in ts::TCPConnection, ts::BinaryFile, and ts::ForkPipe.

◆ isReadStream()

virtual bool ts::StreamInterface::isReadStream ( )

pure virtual

Check if the stream is open for read.

Returns: True if readStream() is possible, false otherwise (write-only, closed, or disconnected stream).

Implemented in ts::TCPConnection, ts::BinaryFile, and ts::ForkPipe.

◆ isWriteStream()

virtual bool ts::StreamInterface::isWriteStream ( )

pure virtual

Check if the stream is open for write.

Returns: True if writeStream() is possible, false otherwise (read-only, closed, or disconnected stream).

Implemented in ts::TCPConnection, ts::BinaryFile, and ts::ForkPipe.

◆ endOfStream()

virtual bool ts::StreamInterface::endOfStream ( )

pure virtual

Check if the end of stream was reached while reading.

Returns: True on end of stream, false otherwise.

Implemented in ts::TCPConnection, ts::BinaryFile, ts::ForkPipe, and ts::TSFile.

◆ WriteStreamHelper()

template<class T >
requires std::derived_from<T, StreamInterface>

static bool ts::StreamInterface::WriteStreamHelper	(	T *	obj,
		const void *	addr,
		size_t	size,
		NonBlockingDevice::IOSB *	iosb
	)

inlinestaticprotected

Implementation helper for fixed-size version of writeStream().

Often, the fixed-size version can be implemented using the variable-size version. However, this works well at a given derivation stage only.

Assume that:

We implement the fixed-size version inside StreamInterface, using the virtual variable-size version.
Class A implements StreamInterface and implements the variable-size version only. The base fixed-size version StreamInterface::writeStream() uses the virtual variable-size version A::writeStream() and it works well.
Class B derives from A. It is an encrypted version of A (think A=TCP, B=TLS). If the implementation of B wants to write raw data (after encryption) calling the fixed-size version A::writeStream(), then this will end up calling the virtual variable-size version B::writeStream(), which will try to encrypt already encrypted data. This is why it is important that each layer of inheritance calls its own version of writeStream().

Template Parameters

T	A subclass of StreamInterface. Write data to the stream. All bytes are written to the stream, blocking or retrying when necessary when the stream is in blocking mode. The base implementation of writeStream() uses the virtual version with a written_size output parameter.

Parameters

[in,out]	obj	Object of class T.
[in]	addr	Address of the data to write.
[in]	size	Size in bytes of the data to write.
[in,out]	iosb	Address of an IOSB structure. If non-null, the stream must be in non-blocking mode. When null, the stream must be in blocking mode (the default). See the description of ts::NonBlockingDevice::IOSB. Important: The parameter iosb should not be used by applications. It should be used only by "reactive classes", which work in combination with a Reactor.

Returns: True on success, false on error or it less than size bytes could be written. In case of non-blocking mode, if the I/O is successfully started but still pending, iosb->pending is set to true and the method returns true.

◆ ReadStreamHelper()

template<class T >
requires std::derived_from<T, StreamInterface>

static bool ts::StreamInterface::ReadStreamHelper	(	T *	obj,
		void *	addr,
		size_t	size,
		const AbortInterface *	abort
	)

inlinestaticprotected

Implementation helper for fixed-size version of readStream().

See writeStreamHelper() for a rationale.

Template Parameters

T	A subclass of StreamInterface.

Parameters

[in,out]	obj	Object of class T.
[out]	addr	Address of the buffer for the incoming data.
[in]	size	Size in bytes of the buffer.
[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 or it less than size bytes could be read.

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

tsStreamInterface.h

Public Member Functions

Static Protected Member Functions

Detailed Description

Member Function Documentation

◆ writeStream() [1/2]

◆ writeStream() [2/2]

◆ readStream() [1/2]

◆ readStream() [2/2]

◆ asyncCompletedStream()

◆ isReadStream()

◆ isWriteStream()

◆ endOfStream()

◆ WriteStreamHelper()

◆ ReadStreamHelper()