Abstract base class for all I/O devices. More...

#include <iodevice.h>

Inheritance diagram for IODevice:

[legend]

Collaboration diagram for IODevice:

[legend]

Public Types
enum	OpenMode { NotOpen = 0x00 , ReadOnly = 0x01 , WriteOnly = 0x02 , ReadWrite = ReadOnly \| WriteOnly , Append = 0x04 \| WriteOnly }
	Mode flags controlling how a device is opened. More...

Public Types inherited from ObjectBase
using	SlotVariantFunc = std::function< void(const VariantList &)>
	Function type for invoking a slot with a list of Variants.

Public Member Functions
	IODevice (ObjectBase *parent=nullptr)
	Constructs an IODevice.

virtual	~IODevice ()
	Destructor.

virtual Error	open (OpenMode mode)=0
	Opens the device with the specified mode.

virtual Error	close ()=0
	Closes the device.

virtual bool	isOpen () const =0
	Returns true if the device is open.

virtual int64_t	read (void *data, int64_t maxSize)=0
	Reads up to maxSize bytes into data.

virtual int64_t	write (const void *data, int64_t maxSize)=0
	Writes up to maxSize bytes from data.

virtual void	flush ()
	Flushes any buffered output data to the underlying device.

virtual int64_t	bytesAvailable () const
	Returns the number of bytes available for reading.

virtual bool	waitForReadyRead (unsigned int timeoutMs=0)
	Waits until data is available for reading or timeout.

virtual bool	waitForBytesWritten (unsigned int timeoutMs=0)
	Waits until all pending data has been written or timeout.

virtual bool	isSequential () const
	Returns true if the device is sequential (non-seekable).

virtual Error	seek (int64_t pos)
	Seeks to the given byte offset from the beginning.

virtual int64_t	pos () const
	Returns the current read/write position.

virtual Result< int64_t >	size () const
	Returns the total size of the device in bytes.

virtual bool	atEnd () const
	Returns true if the current position is at the end.

OpenMode	openMode () const
	Returns the current open mode.

bool	isReadable () const
	Returns true if the device is readable.

bool	isWritable () const
	Returns true if the device is writable.

Error	error () const
	Returns the current error state.

void	clearError ()
	Clears the error state to Ok.

	PROMEKI_SIGNAL (readyRead)
	Emitted when data is available for reading.

	PROMEKI_SIGNAL (bytesWritten, int64_t)
	Emitted when bytes have been written.

	PROMEKI_SIGNAL (errorOccurred, Error)
	Emitted when an error occurs.

	PROMEKI_SIGNAL (aboutToClose)
	Emitted just before the device is closed.

Public Member Functions inherited from ObjectBase
	ObjectBase (ObjectBase *p=nullptr)
	Default ObjectBase constructor.

virtual	~ObjectBase ()
	Destructor. Emits aboutToDestroy, detaches from parent, and destroys children.

ObjectBase *	parent () const
	Returns the parent object, if one. nullptr if none.

void	setParent (ObjectBase *p)
	Sets the parent of this object. If the object already has a parent, it will be removed as a child from the old parent and added as a child to the new one.

const ObjectBaseList &	childList () const
	Returns a list of children of this object.

template<typename... Args>
int	registerSlot (Slot< Args... > *slot)
	Registers a slot with this object and assigns it an ID.

EventLoop *	eventLoop () const
	Returns the EventLoop this object is affiliated with.

void	moveToThread (EventLoop *loop)
	Changes the EventLoop affinity of this object.

int	startTimer (unsigned int intervalMs, bool singleShot=false)
	Starts a timer on this object's EventLoop.

void	stopTimer (int timerId)
	Stops a timer previously started with startTimer().

template<typename... Args>
PROMEKI_NAMESPACE_BEGIN void	connect (Signal< Args... > signal, Slot< Args... > slot)

Protected Member Functions
void	setOpenMode (OpenMode mode)
	Sets the open mode.

void	setError (const Error &err)
	Sets the error state and emits errorOccurred.

Protected Member Functions inherited from ObjectBase
ObjectBase *	signalSender ()
	Returns the ObjectBase that emitted the signal currently being handled.

virtual void	event (Event *e)
	Called by EventLoop to deliver events to this object.

virtual void	timerEvent (TimerEvent *e)
	Called when a timer fires for this object.

Additional Inherited Members
Static Public Member Functions inherited from ObjectBase
static const MetaInfo &	metaInfo ()
	Returns the MetaInfo for the ObjectBase class.

template<typename... Args>
static void	connect (Signal< Args... > signal, Slot< Args... > slot)
	connects a signal and slot together. This function assumes both the signal and slot exist in a ObjectBase or derived object

Public Attributes inherited from ObjectBase
Signal< ObjectBase * >	aboutToDestroySignal = Signal< ObjectBase * >(this, aboutToDestroySignalName)

Static Public Attributes inherited from ObjectBase
static constexpr const char *	aboutToDestroySignalName = PROMEKI_STRINGIFY( aboutToDestroy ) "(" PROMEKI_STRINGIFY_ARGS( ObjectBase * ) ")"

static SignalMeta	aboutToDestroySignalMeta = SignalMeta(metaInfo(), aboutToDestroySignalName)

Detailed Description

Abstract base class for all I/O devices.

IODevice provides a uniform interface for reading and writing data to devices such as files, sockets, pipes, and in-memory buffers. All I/O device classes in promeki derive from this class.

This class must only be used from the thread that created it (or moved to via moveToThread()).

Member Enumeration Documentation

◆ OpenMode

enum IODevice::OpenMode

Mode flags controlling how a device is opened.

Enumerator
NotOpen	Device is not open.
ReadOnly	Open for reading only.
WriteOnly	Open for writing only.
ReadWrite	Open for reading and writing.
Append	Open for appending (implies WriteOnly).

Constructor & Destructor Documentation

◆ IODevice()

IODevice::IODevice ( ObjectBase * parent = nullptr )

inline

Constructs an IODevice.

Parameters

parent The parent object, or nullptr.

Member Function Documentation

◆ atEnd()

virtual bool IODevice::atEnd ( ) const

virtual

Returns true if the current position is at the end.

The default implementation returns true if pos() >= size().

Returns: true if at end of device.

Reimplemented in BufferIODevice, File, FileIODevice, and StringIODevice.

◆ bytesAvailable()

virtual int64_t IODevice::bytesAvailable ( ) const

virtual

Returns the number of bytes available for reading.

The default implementation returns 0.

Returns: The number of bytes available.

Reimplemented in BufferedIODevice, BufferIODevice, StringIODevice, TcpSocket, and UdpSocket.

◆ close()

virtual Error IODevice::close ( )

pure virtual

Closes the device.

Returns: Error::Ok on success, or an error on failure.

Implemented in BufferIODevice, File, FileIODevice, StreamStringIODevice, StringIODevice, RawSocket, TcpSocket, and UdpSocket.

◆ error()

Error IODevice::error ( ) const

inline

Returns the current error state.

Returns: The last error set on this device.

◆ flush()

virtual void IODevice::flush ( )

virtual

Flushes any buffered output data to the underlying device.

The default implementation is a no-op, suitable for unbuffered devices such as in-memory buffers. Subclasses that wrap buffered I/O (e.g. stdio FILE*) should override this.

Reimplemented in FileIODevice, and StreamStringIODevice.

◆ isOpen()

virtual bool IODevice::isOpen ( ) const

pure virtual

Returns true if the device is open.

Returns: true if the device is currently open.

Implemented in BufferIODevice, File, FileIODevice, StreamStringIODevice, StringIODevice, RawSocket, TcpSocket, and UdpSocket.

◆ isReadable()

bool IODevice::isReadable ( ) const

inline

Returns true if the device is readable.

Returns: true if the ReadOnly bit is set in the open mode.

◆ isSequential()

virtual bool IODevice::isSequential ( ) const

virtual

Returns true if the device is sequential (non-seekable).

Sequential devices (pipes, sockets) cannot be seeked. The default implementation returns false.

Returns: true if the device is sequential.

Reimplemented in BufferIODevice, File, FileIODevice, StreamStringIODevice, StringIODevice, and AbstractSocket.

◆ isWritable()

bool IODevice::isWritable ( ) const

inline

Returns true if the device is writable.

Returns: true if the WriteOnly bit is set in the open mode.

◆ open()

virtual Error IODevice::open ( OpenMode mode )

pure virtual

Opens the device with the specified mode.

Parameters

mode	The open mode (ReadOnly, WriteOnly, ReadWrite, or Append).

Returns: Error::Ok on success, or an error on failure.

Implemented in BufferIODevice, File, FileIODevice, StreamStringIODevice, StringIODevice, RawSocket, TcpSocket, and UdpSocket.

◆ openMode()

OpenMode IODevice::openMode ( ) const

inline

Returns the current open mode.

Returns: The OpenMode the device was opened with.

◆ pos()

virtual int64_t IODevice::pos ( ) const

virtual

Returns the current read/write position.

The default implementation returns 0.

Returns: The current position in bytes.

Reimplemented in BufferIODevice, File, FileIODevice, and StringIODevice.

◆ PROMEKI_SIGNAL() [1/4]

IODevice::PROMEKI_SIGNAL ( aboutToClose )

Emitted just before the device is closed.

Signal:

◆ PROMEKI_SIGNAL() [2/4]

IODevice::PROMEKI_SIGNAL	(	bytesWritten	,
		int64_t
	)

Emitted when bytes have been written.

Signal:

◆ PROMEKI_SIGNAL() [3/4]

IODevice::PROMEKI_SIGNAL	(	errorOccurred	,
		Error
	)

Emitted when an error occurs.

Signal:

◆ PROMEKI_SIGNAL() [4/4]

IODevice::PROMEKI_SIGNAL ( readyRead )

Emitted when data is available for reading.

Signal:

◆ read()

virtual int64_t IODevice::read	(	void *	data,
		int64_t	maxSize
	)

pure virtual

Reads up to maxSize bytes into data.

Parameters

data	Pointer to the buffer to read into.
maxSize	Maximum number of bytes to read.

Returns: The number of bytes read, or -1 on error.

Implemented in StreamStringIODevice, BufferedIODevice, BufferIODevice, FileIODevice, StringIODevice, RawSocket, TcpSocket, and UdpSocket.

◆ seek()

virtual Error IODevice::seek ( int64_t pos )

virtual

Seeks to the given byte offset from the beginning.

Parameters

pos	The byte offset to seek to.

Returns: Error::Ok on success, or an error on failure.

Reimplemented in File, BufferIODevice, FileIODevice, and StringIODevice.

◆ setError()

void IODevice::setError ( const Error & err )

inlineprotected

Sets the error state and emits errorOccurred.

Parameters

err	The error to set.

◆ setOpenMode()

void IODevice::setOpenMode ( OpenMode mode )

inlineprotected

Sets the open mode.

Call this from subclass open() implementations.

Parameters

mode	The open mode to set.

◆ size()

virtual Result< int64_t > IODevice::size ( ) const

virtual

Returns the total size of the device in bytes.

The default implementation returns 0.

Returns: A Result containing the device size, or an error.

Reimplemented in BufferIODevice, File, and StringIODevice.

◆ waitForBytesWritten()

virtual bool IODevice::waitForBytesWritten ( unsigned int timeoutMs = 0 )

virtual

Waits until all pending data has been written or timeout.

Parameters

timeoutMs Timeout in milliseconds (0 = wait forever).

Returns: true if all data was written, false on timeout.

◆ waitForReadyRead()

virtual bool IODevice::waitForReadyRead ( unsigned int timeoutMs = 0 )

virtual

Waits until data is available for reading or timeout.

Parameters

timeoutMs Timeout in milliseconds (0 = wait forever).

Returns: true if data became available, false on timeout.

◆ write()

virtual int64_t IODevice::write	(	const void *	data,
		int64_t	maxSize
	)

pure virtual

Writes up to maxSize bytes from data.

Parameters

data	Pointer to the data to write.
maxSize	Number of bytes to write.

Returns: The number of bytes written, or -1 on error.

Implemented in BufferIODevice, File, FileIODevice, StreamStringIODevice, StringIODevice, RawSocket, TcpSocket, and UdpSocket.

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

include/promeki/core/iodevice.h

Public Types

Public Member Functions

Protected Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ OpenMode

Constructor & Destructor Documentation

◆ IODevice()

Member Function Documentation

◆ atEnd()

◆ bytesAvailable()

◆ close()

◆ error()

◆ flush()

◆ isOpen()

◆ isReadable()

◆ isSequential()

◆ isWritable()

◆ open()

◆ openMode()

◆ pos()

◆ PROMEKI_SIGNAL() [1/4]

◆ PROMEKI_SIGNAL() [2/4]

◆ PROMEKI_SIGNAL() [3/4]

◆ PROMEKI_SIGNAL() [4/4]

◆ read()

◆ seek()

◆ setError()

◆ setOpenMode()

◆ size()

◆ waitForBytesWritten()

◆ waitForReadyRead()

◆ write()