Binary stream file, with optional asynchronous I/O. More...

#include <tsBinaryFile.h>

Inheritance diagram for ts::BinaryFile:

[legend]

Collaboration diagram for ts::BinaryFile:

[legend]

Public Types
enum	OpenFlags { NONE = 0x0000 , READ = 0x0001 , WRITE = 0x0002 , APPEND = 0x0004 , KEEP = 0x0008 , SHARED = 0x0010 , TEMPORARY = 0x0020 , REOPEN = 0x0040 , REOPEN_SPEC = 0x0080 }
	Flags for open(). More...

Public Member Functions
	BinaryFile (Report *report, bool non_blocking=false)
	Constructor.

	BinaryFile (ReporterBase *delegate, bool non_blocking=false)
	Constructor.

virtual	~BinaryFile () override
	Destructor.

void	abort ()
	Abort any currenly read/write operation in progress.

virtual bool	asyncCompletedStream (IOSB *iosb) override
	Update the status of an asynchronous readStream() or writeStream() after it completed.

virtual bool	close (bool silent=false)
	Close the file.

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

UString	getDisplayFileName () const
	Get the file name as a display string.

fs::path	getFileName () const
	Get the file name.

OpenFlags	getFlags () const
	Get the flags which were used when the file was open.

SysHandleType	getHandle () const
	Get the underlying file descriptor or device handle.

virtual SysHandleType	getReadHandle () const override
	Get the underlying file descriptor or device handle for read operations.

SysSocketType	getReadSocket () const
	Get the underlying file descriptor or device handle as a system socket handle for read operations.

SysSocketType	getSocket () const
	Get the underlying file descriptor or device handle as a system socket handle.

virtual SysHandleType	getWriteHandle () const override
	Get the underlying file descriptor or device handle for write operations.

SysSocketType	getWriteSocket () const
	Get the underlying file descriptor or device handle as a system socket handle for write operations.

bool	isNonBlocking () const
	Check if the device is in non-blocking mode.

bool	isOpen () const
	Check if the file is open.

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

bool	isSupportedByReactor (bool recheck=false)
	Check if the device is supported by a reactor for non-blocking or asynchronous I/O.

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

bool	muteReport (bool mute)
	Temporarily mute the associated report.

virtual bool	open (const fs::path &filename, OpenFlags flags)
	Open or create the file (generic form).

bool	openRead (const fs::path &filename, size_t repeat_count, uint64_t start_offset)
	Open the file for read with a given repetition count.

bool	openRead (const fs::path &filename, uint64_t start_offset)
	Open the file for read in rewindable mode.

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

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

virtual Report &	report () const override
	Access the Report which is associated with this object.

bool	rewind ()
	Rewind the file.

bool	seekByte (uint64_t byte_index)
	Seek the file at a specified byte index.

bool	setNonBlocking (bool non_blocking)
	Set the device in non-blocking mode.

Report *	setReport (Report *report)
	Associate this object with another Report to log errors.

ReporterBase *	setReport (ReporterBase *delegate)
	Associate this object with another ReporterBase to log errors.

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

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

Static Public Member Functions
static bool	IsPendingStatus (int error_code)
	This static method checks if a system error code means "I/O in progress" (asynchronous I/O) or "I/O would block" (non-blocking I/O).

static int	SilentLevel (bool silent, int default_severity=Severity::Error)
	Compute a log severity level from a "silent" parameter.

Protected Member Functions
virtual bool	allowSetNonBlocking () const override
	Check that the non-blocking mode can be set.

bool	checkNonBlocking (bool non_blocking, const UChar *opname)
	Check the blocking mode of a device.

bool	checkNonBlocking (IOSB iosb, const UChar opname)
	Check the blocking mode of a device.

int	genericSystemRead (void addr, size_t max_size, size_t &ret_size, const AbortInterface abort, NonBlockingDevice::IOSB *iosb, uint64_t position)
	Generic system read operation.

int	genericSystemWrite (const void addr, size_t size, size_t &written_size, NonBlockingDevice::IOSB iosb, uint64_t position)
	Generic system write operation.

bool	setSystemNonBlocking (bool non_blocking)
	Low-level method to set the system file or socket descriptor in non-blocking mode.

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

Binary stream file, with optional asynchronous I/O.

Member Enumeration Documentation

◆ OpenFlags

enum ts::BinaryFile::OpenFlags

Flags for open().

Enumerator
NONE	No option, do not open the file.
READ	Read the file.
WRITE	Write the file.
APPEND	Append data to an existing file.
KEEP	Keep previous file with same name. Fail if it already exists.
SHARED	Write open with shared read for other processes. Windows only. Always shared on Unix.
TEMPORARY	Temporary file, deleted on close, not always visible in the file system.
REOPEN	Close and reopen the file instead of rewind to start of file when looping on input file.
REOPEN_SPEC	Force REOPEN when the file is not a regular file.

Constructor & Destructor Documentation

◆ BinaryFile() [1/2]

ts::BinaryFile::BinaryFile	(	Report *	report,
		bool	non_blocking = `false`
	)

explicit

Constructor.

Parameters

[in]	report	Where to report errors. The report object must remain valid as long as this object exists or setReport() is used with another Report object. If report is null, log messages are discarded.
[in]	non_blocking	It true, the file is initially set in non-blocking mode.

◆ BinaryFile() [2/2]

ts::BinaryFile::BinaryFile	(	ReporterBase *	delegate,
		bool	non_blocking = `false`
	)

explicit

Constructor.

Parameters

[in]	delegate	Use the report of another ReporterBase. If delegate is null, log messages are discarded.
[in]	non_blocking	It true, the file is initially set in non-blocking mode.

Member Function Documentation

◆ openRead() [1/2]

bool ts::BinaryFile::openRead	(	const fs::path &	filename,
		size_t	repeat_count,
		uint64_t	start_offset
	)

Open the file for read with a given repetition count.

The file is automatically read a given number of times before declaring an end-of-file. No rewind or seek operation is allowed because it would break the repetition.

Parameters

[in]	filename	File name. If empty or "-", use standard input. Must be a regular file if start_offset is not zero. If repeat_count is not 1 and the file is not a regular one, the file is closed and reopened instead of being rewound.
[in]	repeat_count	Reading the file loops back after end of file until all repeat are done. If zero, infinitely repeat.
[in]	start_offset	Offset in bytes from the beginning of the file where to start reading data at each iteration.

Returns: True on success, false on error.

◆ openRead() [2/2]

bool ts::BinaryFile::openRead	(	const fs::path &	filename,
		uint64_t	start_offset
	)

Open the file for read in rewindable mode.

The file must be a rewindable file, eg. not a pipe. There is no repeat count, rewind must be done explicitly.

Parameters

[in]	filename	File name. If empty or "-", use standard input.
[in]	start_offset	Offset in bytes from the beginning of the file where to start reading data.

Returns: True on success, false on error.

See also: rewind(); seekByte()

◆ open()

virtual bool ts::BinaryFile::open	(	const fs::path &	filename,
		OpenFlags	flags
	)

virtual

Open or create the file (generic form).

The file is rewindable if the underlying file is seekable, eg. not a pipe.

Parameters

[in]	filename	File name. If empty or "-", use standard input or output. If filename is empty, flags cannot contain both READ and WRITE.
[in]	flags	Bit mask of open flags.

Returns: True on success, false on error.

Reimplemented in ts::TSFile, and ts::TSFileOutputResync.

◆ getFlags()

OpenFlags ts::BinaryFile::getFlags ( ) const

inline

Get the flags which were used when the file was open.

Returns: The flags.

◆ isOpen()

bool ts::BinaryFile::isOpen ( ) const

inline

Check if the file is open.

Returns: True if the file is open.

◆ getFileName()

fs::path ts::BinaryFile::getFileName ( ) const

inline

Get the file name.

Returns: The file name.

◆ getDisplayFileName()

UString ts::BinaryFile::getDisplayFileName ( ) const

Get the file name as a display string.

Returns: The file name as a display string. Not always a valid file name. Use in error messages only.

◆ close()

virtual bool ts::BinaryFile::close ( bool silent = false )

virtual

Close the file.

Parameters

[in] silent If true, do not report errors. This is typically useful when the object is in some error condition and closing it is necessary although it may generate additional meaningless errors.

Returns: True on success, false on error.

Reimplemented in ts::TSFile.

◆ abort()

void ts::BinaryFile::abort ( )

Abort any currenly read/write operation in progress.

The file is left in a broken state and can be only closed.

◆ rewind()

bool ts::BinaryFile::rewind ( )

inline

Rewind the file.

The file must have been opened in rewindable mode. If the file file was opened with a start_offset different from 0, rewinding the file means restarting at this start_offset.

Returns: True on success, false on error.

◆ seekByte()

bool ts::BinaryFile::seekByte ( uint64_t byte_index )

Seek the file at a specified byte index.

The file must have been opened in rewindable mode.

Parameters

[in] byte_index Seek the file to this specified byte index (plus the specified start_offset from open()).

Returns: True on success, false on error.

◆ getReadHandle()

virtual SysHandleType ts::BinaryFile::getReadHandle ( ) const

overridevirtual

Get the underlying file descriptor or device handle for read operations.

Subclasses should override this method.

Returns: The underlying file descriptor for read operations or SYS_HANDLE_INVALID if the device is not open for read.

See also: getHandle()

Reimplemented from ts::NonBlockingDevice.

◆ getWriteHandle()

virtual SysHandleType ts::BinaryFile::getWriteHandle ( ) const

overridevirtual

Get the underlying file descriptor or device handle for write operations.

Subclasses should override this method.

Returns: The underlying file descriptor for write operations or SYS_HANDLE_INVALID if the device is not open for write.

See also: getHandle()

Reimplemented from ts::NonBlockingDevice.

◆ readStream() [1/2]

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

overridevirtual

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.

Implements ts::StreamInterface.

◆ readStream() [2/2]

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

overridevirtual

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.

Implements ts::StreamInterface.

◆ writeStream() [1/2]

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

overridevirtual

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.

Implements ts::StreamInterface.

◆ writeStream() [2/2]

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

overridevirtual

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.

Implements ts::StreamInterface.

◆ asyncCompletedStream()

virtual bool ts::BinaryFile::asyncCompletedStream ( IOSB * iosb )

overridevirtual

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.

Implements ts::StreamInterface.

◆ isReadStream()

virtual bool ts::BinaryFile::isReadStream ( )

overridevirtual

Check if the stream is open for read.

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

Implements ts::StreamInterface.

◆ isWriteStream()

virtual bool ts::BinaryFile::isWriteStream ( )

overridevirtual

Check if the stream is open for write.

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

Implements ts::StreamInterface.

◆ endOfStream()

virtual bool ts::BinaryFile::endOfStream ( )

overridevirtual

Check if the end of stream was reached while reading.

Returns: True on end of stream, false otherwise.

Implements ts::StreamInterface.

Reimplemented in ts::TSFile.

◆ allowSetNonBlocking()

virtual bool ts::BinaryFile::allowSetNonBlocking ( ) const

overrideprotectedvirtual

Check that the non-blocking mode can be set.

Must be implemented by subclasses which do not support setting the non-blocking in certain states, such as after being opened. The default implementation always allows setting the non-blocking mode.

Returns: True if setting the non-blocking mode is allowed, false otherwise.

Reimplemented from ts::NonBlockingDevice.

◆ setNonBlocking()

bool ts::NonBlockingDevice::setNonBlocking ( bool non_blocking )

inherited

Set the device in non-blocking mode.

Important: Usually, this method must be called before opening the device, whatever it means. Otherwise it is ignored and the device blocking mode is unchanged.

Parameters

[in] non_blocking It true, the device is set in non-blocking mode.

Returns: True on success, false if the device is already open and the non-blocking mode is unchanged.

◆ isNonBlocking()

bool ts::NonBlockingDevice::isNonBlocking ( ) const

inlineinherited

Check if the device is in non-blocking mode.

Returns: True if the device is in non-blocking mode, false otherwise.

See also: setNonBlocking()

◆ isSupportedByReactor()

bool ts::NonBlockingDevice::isSupportedByReactor ( bool recheck = false )

inherited

Check if the device is supported by a reactor for non-blocking or asynchronous I/O.

Parameters

[in] recheck If true, force a recheck. If false and the device was previously checked, return the previous cached value.

Returns: True if the device is supported by a reactor for non-blocking or asynchronous I/O, false otherwise.

◆ IsPendingStatus()

static bool ts::NonBlockingDevice::IsPendingStatus ( int error_code )

inlinestaticinherited

This static method checks if a system error code means "I/O in progress" (asynchronous I/O) or "I/O would block" (non-blocking I/O).

Parameters

[in] error_code System error code.

Returns: True if error_code is an in-progress/would-block one.

◆ getHandle()

SysHandleType ts::NonBlockingDevice::getHandle ( ) const

inherited

Get the underlying file descriptor or device handle.

This method is reserved for low-level operations and should not be used by normal applications.

On UNIX systems, sockets are standard file descriptors. On Windows systems, sockets and devices handles are two distinct types (SOCKET, an integer type, and HANDLE, a pointer type). However, SOCKET and HANDLE have the same size and can be converted between each other. In practice, all Windows device handles are pointers. When Microsoft decided to implement the BSD socket API, they needed to represent sockets as integers. The integer is simply a cast of the HANDLE pointer.

In practice, the methods getHandle() and getSocket() return the same value, represented as two different portable types, SysHandleType and SysSocketType. Note that this types are defined as their real representation. On UNIX systems, both are defined as int and are compatible. However, on Windows systems, they are defined as HANDLE and SOCKET and are not compatible. So, accidentally mixing the two compiles on UNIX but not on Windows. Be careful to use the right type for the right usage.

There is one important difference between getHandle() and getSocket(): the error values, SYS_HANDLE_INVALID and SYS_SOCKET_INVALID. Be careful, these constants have distinct binary values on Windows. This is the only case were it is not possible to cast between a SysHandleType value and a SysSocketType value. This is why it is recommended to always use getHandle() when a SysHandleType is required and getSocket() when a SysSocketType is required.

A subclass which uses file descriptors or device handles for read, write, or both, must override the methods getReadHandle(), getWriteHandle(), or both. If the two types of operations use the same file descriptor, the two methods must return the same value.

An application should call getReadHandle() for read operations and getWriteHandle() for write operations. The method getHandle() returns getReadHandle() if its returns a valid value, and getWriteHandle() otherwise.

Returns: The underlying file descriptor or device handler. Return SYS_HANDLE_INVALID if the socket is not open.

◆ getSocket()

SysSocketType ts::NonBlockingDevice::getSocket ( ) const

inherited

Get the underlying file descriptor or device handle as a system socket handle.

Returns: The underlying socket descriptor. Return SYS_SOCKET_INVALID if the socket is not open.

See also: getHandle()

◆ getReadSocket()

SysSocketType ts::NonBlockingDevice::getReadSocket ( ) const

inherited

Get the underlying file descriptor or device handle as a system socket handle for read operations.

Returns: The underlying file descriptor for read operations or SYS_SOCKET_INVALID if the socket is not open for read.

See also: getHandle()

◆ getWriteSocket()

SysSocketType ts::NonBlockingDevice::getWriteSocket ( ) const

inherited

Get the underlying file descriptor or device handle as a system socket handle for write operations.

Returns: The underlying file descriptor for read operations or SYS_SOCKET_INVALID if the socket is not open for write.

See also: getHandle()

◆ checkNonBlocking() [1/2]

bool ts::NonBlockingDevice::checkNonBlocking	(	bool	non_blocking,
		const UChar *	opname
	)

protectedinherited

Check the blocking mode of a device.

Called by subclass methods which are explicitly called in blocking or non-blocking mode.

Parameters

[in]	non_blocking	The required non-blocking mode.
[in]	opname	Name of the operation, for the error message.

Returns: True on success, false on error.

◆ checkNonBlocking() [2/2]

bool ts::NonBlockingDevice::checkNonBlocking	(	IOSB *	iosb,
		const UChar *	opname
	)

protectedinherited

Check the blocking mode of a device.

Called by subclass methods which are explicitly called in blocking or non-blocking mode.

Parameters

[in,out]	iosb	Address of an IOSB structure. If non-null, we are in non-blocking mode. When null, we are in blocking mode. When non-null, pending is reset to false and overlap is zeroed.
[in]	opname	Name of the operation, for the error message.

Returns: True on success, false on error.

◆ setSystemNonBlocking()

bool ts::NonBlockingDevice::setSystemNonBlocking ( bool non_blocking )

protectedinherited

Low-level method to set the system file or socket descriptor in non-blocking mode.

Parameters

[in] non_blocking It true, the device is set in non-blocking mode.

Returns: True on success, false on error.

Summary: Do not use this method unless you exactly know what you are doing.

UNIX: Depending on the way a file descriptor is created, it may be possible to specify the non-blocking mode from the beginning. Or it can be somehow inherited. However, this is not portable.

Examples:

On Linux and FreeBSD, a socket can be directly created in non-blocking mode using the flag SOCK_NONBLOCK in the 'type' parameter of the socket() system call. However, it does not work on macOS.
On macOS (and maybe FreeBSD), when a server socket is in non-blocking mode, all client session sockets which are created by accept() are also in non-blocking mode. However, on Linux, they are in blocking mode.

In all cases, it is possible to set a file descriptor in non-blocking mode at any time using the method setSystemNonBlocking(). This method uses fcntl(F_SETFL) to alter the file descriptor's flags.

Windows: The natural way of not being blocked on I/O on Windows is asynchronous I/O. To increase the general confusion, there is some form of non-blocking mode on Windows sockets, and only sockets, not other forms of file handles. This mode is activated using "ioctlsocket(fd, FIONBIO, &mode)". When this mode is active, socket I/O become similar to UNIX: they immediately either succeed or fail, but never block. However, there is no way to get notified when the I/O becomes possible. There is no equivalent to epoll (Linux) or kqueue (macOS and BSD). The Windows I/O Completion Ports can only work on asynchronous I/O, using OVERLAPPED structures. Because this form of non-blocking mode is mostly useless in practice, we do not use it and the method setSystemNonBlocking() does nothing on Windows.

See also: https://learn.microsoft.com/en-us/archive/blogs/csliu/io-concept-blockingnon-blocking-vs-syncasync

◆ genericSystemWrite()

int ts::NonBlockingDevice::genericSystemWrite	(	const void *	addr,
		size_t	size,
		size_t &	written_size,
		NonBlockingDevice::IOSB *	iosb,
		uint64_t	position
	)

protectedinherited

Generic system write operation.

This is a convenience method which can be used (or not) by subclasses when the system calls write() (UNIX) or WriteFile() (Windows) are appropriate.

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.
[in]	position	This value is only used on Windows with asynchronous I/O on disk file. On Windows, when asynchronous I/O are used on random access files, the file position is not maintained. Each read or write operation is performed at the specified absolute position.

Returns: Error code. When the I/O is non-blocking/asynchronous and pending, return SYS_SUCCESS and iosb->pending is true. Return SYS_EOF when it is no longer possible to write (e.g. broken pipe).

◆ genericSystemRead()

int ts::NonBlockingDevice::genericSystemRead	(	void *	addr,
		size_t	max_size,
		size_t &	ret_size,
		const AbortInterface *	abort,
		NonBlockingDevice::IOSB *	iosb,
		uint64_t	position
	)

protectedinherited

Generic system read operation.

This is a convenience method which can be used (or not) by subclasses when the system calls read() (UNIX) or ReadFile() (Windows) are appropriate.

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.
[in]	position	This value is only used on Windows with asynchronous I/O on disk file. On Windows, when asynchronous I/O are used on random access files, the file position is not maintained. Each read or write operation is performed at the specified absolute position.

Returns: Error code. When the I/O is non-blocking/asynchronous and pending, return SYS_SUCCESS and iosb->pending is true. Return SYS_EOF when it is no longer possible to read.

◆ report()

virtual Report & ts::ReporterBase::report ( ) const

overridevirtualinherited

Access the Report which is associated with this object.

Can be called from another thread only if the Report object is thread-safe.

Returns: A reference to the associated report.

Implements ts::ReporterInterface.

◆ setReport() [1/2]

Report * ts::ReporterBase::setReport ( Report * report )

inherited

Associate this object with another Report to log errors.

Parameters

[in] report Where to report errors. The report object must remain valid as long as this object exists or setReport() is used with another Report object. If report is null, log messages are discarded.

Returns: The address of the previous Report object or a null pointer if there was none.

◆ setReport() [2/2]

ReporterBase * ts::ReporterBase::setReport ( ReporterBase * delegate )

inherited

Associate this object with another ReporterBase to log errors.

Parameters

[in] delegate Use the report of another ReporterBase. If delegate is null, the previous explicit Report is used..

Returns: The address of the previous ReporterBase object or a null pointer if there was none.

◆ muteReport()

bool ts::ReporterBase::muteReport ( bool mute )

inherited

Temporarily mute the associated report.

Parameters

[in] mute It true, report() will return a null report (log messages are discarded), until muteReport() is invoked again with mute set to false.

Returns: Previous state of the mute field.

◆ SilentLevel()

static int ts::ReporterBase::SilentLevel	(	bool	silent,
		int	default_severity = `Severity::Error`
	)

inlinestaticinherited

Compute a log severity level from a "silent" parameter.

Some subclass methods have a "silent" parameter to avoid reporting errors which may be insignificant, typically when closing a device after an error, in which case the close operation may produce other errors if the previous error left the device in an inconsistent state. While those errors should not be displayed as errors, we still display them at debug level.

Parameters

[in]	silent	If true, do not report errors, report debug messages instead.
[in]	default_severity	Default severity, in non-silent mode (error by default).

Returns: Error when silent is false, Debug otherwise.

◆ 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
	)

inlinestaticprotectedinherited

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
	)

inlinestaticprotectedinherited

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:

tsBinaryFile.h

Public Types

Public Member Functions

Static Public Member Functions

Protected Member Functions

Static Protected Member Functions

Detailed Description

Member Enumeration Documentation

◆ OpenFlags

Constructor & Destructor Documentation

◆ BinaryFile() [1/2]

◆ BinaryFile() [2/2]

Member Function Documentation

◆ openRead() [1/2]

◆ openRead() [2/2]

◆ open()

◆ getFlags()

◆ isOpen()

◆ getFileName()

◆ getDisplayFileName()

◆ close()

◆ abort()

◆ rewind()

◆ seekByte()

◆ getReadHandle()

◆ getWriteHandle()

◆ readStream() [1/2]

◆ readStream() [2/2]

◆ writeStream() [1/2]

◆ writeStream() [2/2]

◆ asyncCompletedStream()

◆ isReadStream()

◆ isWriteStream()

◆ endOfStream()

◆ allowSetNonBlocking()

◆ setNonBlocking()

◆ isNonBlocking()

◆ isSupportedByReactor()

◆ IsPendingStatus()

◆ getHandle()

◆ getSocket()

◆ getReadSocket()

◆ getWriteSocket()

◆ checkNonBlocking() [1/2]

◆ checkNonBlocking() [2/2]

◆ setSystemNonBlocking()

◆ genericSystemWrite()

◆ genericSystemRead()

◆ report()

◆ setReport() [1/2]

◆ setReport() [2/2]

◆ muteReport()

◆ SilentLevel()

◆ WriteStreamHelper()

◆ ReadStreamHelper()