IODevice wrapping a C stdio FILE pointer. More...

#include <fileiodevice.h>

Inheritance diagram for FileIODevice:

[legend]

Collaboration diagram for FileIODevice:

[legend]

Public Types
enum	Flag { NoFlags = 0x00 , OwnsFile = 0x01 }
	Flags for the FILE* constructor. More...

Public Types inherited from IODevice
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
	FileIODevice (FILE file, OpenMode mode, int flags=NoFlags, ObjectBase parent=nullptr)
	Constructs a FileIODevice wrapping an external FILE.

	FileIODevice (const String &filename, ObjectBase *parent=nullptr)
	Constructs a FileIODevice with a filename.

	FileIODevice (ObjectBase *parent=nullptr)
	Constructs a FileIODevice with no FILE or filename.

	~FileIODevice () override
	Destructor. Closes and fclose's if owned.

	FileIODevice (const FileIODevice &)=delete
	Deleted copy constructor (non-copyable).

FileIODevice &	operator= (const FileIODevice &)=delete
	Deleted copy assignment (non-copyable).

void	setFilename (const String &filename)
	Sets the filename for fopen-based opening.

const String &	filename () const
	Returns the filename, or an empty string if none was set.

FILE *	file () const
	Returns the underlying FILE pointer, or nullptr.

bool	ownsFile () const
	Returns true if the device owns the FILE pointer.

FILE *	takeFile ()
	Transfers ownership of the FILE pointer to the caller.

Error	open (OpenMode mode) override
	Opens the device.

Error	close () override
	Closes the device.

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

bool	isOpen () const override
	Returns true if the device is open.

int64_t	read (void *data, int64_t maxSize) override
	Reads up to maxSize bytes into data.

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

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

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

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

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

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

virtual	~IODevice ()
	Destructor.

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 Result< int64_t >	size () const
	Returns the total size of the device in bytes.

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)

Static Public Member Functions
static FileIODevice *	stdinDevice ()
	Returns a singleton FileIODevice wrapping C stdin.

static FileIODevice *	stdoutDevice ()
	Returns a singleton FileIODevice wrapping C stdout.

static FileIODevice *	stderrDevice ()
	Returns a singleton FileIODevice wrapping C stderr.

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

Additional Inherited Members
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)

Protected Member Functions inherited from IODevice
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.

Detailed Description

IODevice wrapping a C stdio FILE pointer.

FileIODevice adapts a FILE* to the IODevice interface. It supports two usage patterns:

External FILE (e.g. stdin, stdout, stderr): Construct with a FILE* and OpenMode. The device is immediately open. Ownership is controlled by the OwnsFile flag — when set, the FILE is fclose'd on close() or destruction. Use takeFile() to reclaim ownership.
FileIODevice dev(stdout, IODevice::WriteOnly);

dev << "hello";

FileIODevice
IODevice wrapping a C stdio FILE pointer.
Definition fileiodevice.h:47

IODevice::WriteOnly
@ WriteOnly
Open for writing only.
Definition iodevice.h:36

List
Dynamic array container wrapping std::vector.
Definition list.h:40

Filename-based (fopen): Set a filename via the constructor or setFilename(), then call open(). The FILE is created internally and owned by the device.
FileIODevice dev("/tmp/log.txt");

dev.open(IODevice::WriteOnly);

Sequential behavior: isSequential() returns true. For seekable files, seek() and pos() delegate to fseek/ftell and will succeed if the underlying FILE supports it.

Member Enumeration Documentation

◆ Flag

enum FileIODevice::Flag

Flags for the FILE* constructor.

Enumerator
NoFlags	Default: device does not own the FILE.
OwnsFile	Device will fclose the FILE on close/destruct.

Constructor & Destructor Documentation

◆ FileIODevice() [1/3]

FileIODevice::FileIODevice	(	FILE *	file,
		OpenMode	mode,
		int	flags = `NoFlags`,
		ObjectBase *	parent = `nullptr`
	)

Constructs a FileIODevice wrapping an external FILE.

The device is immediately open with the given mode. If OwnsFile is set, the FILE will be fclose'd on close() or destruction.

Parameters

file	The FILE pointer to wrap.
mode	The open mode (ReadOnly, WriteOnly, or ReadWrite).
flags	Ownership flags.
parent	The parent object, or nullptr.

◆ FileIODevice() [2/3]

FileIODevice::FileIODevice	(	const String &	filename,
		ObjectBase *	parent = `nullptr`
	)

explicit

Constructs a FileIODevice with a filename.

The device is not open until open() is called. The FILE is created via fopen and owned by the device.

Parameters

filename	The path to the file.
parent	The parent object, or nullptr.

◆ FileIODevice() [3/3]

FileIODevice::FileIODevice ( ObjectBase * parent = nullptr )

explicit

Constructs a FileIODevice with no FILE or filename.

Set a filename via setFilename() or provide a FILE via the other constructor before opening.

Parameters

parent The parent object, or nullptr.

Member Function Documentation

◆ atEnd()

bool FileIODevice::atEnd ( ) const

overridevirtual

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 from IODevice.

◆ close()

Error FileIODevice::close ( )

overridevirtual

Closes the device.

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

Implements IODevice.

◆ file()

FILE * FileIODevice::file ( ) const

inline

Returns the underlying FILE pointer, or nullptr.

Returns: The FILE pointer.

◆ filename()

const String & FileIODevice::filename ( ) const

inline

Returns the filename, or an empty string if none was set.

Returns: The filename.

◆ flush()

void FileIODevice::flush ( )

overridevirtual

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 from IODevice.

◆ isOpen()

bool FileIODevice::isOpen ( ) const

overridevirtual

Returns true if the device is open.

Returns: true if the device is currently open.

Implements IODevice.

◆ isSequential()

bool FileIODevice::isSequential ( ) const

overridevirtual

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 from IODevice.

◆ open()

Error FileIODevice::open ( OpenMode mode )

overridevirtual

Opens the device.

If a filename is set, the FILE is created via fopen. If a FILE was provided at construction, this returns AlreadyOpen (the device is already open).

Parameters

mode	The open mode.

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

Implements IODevice.

◆ ownsFile()

bool FileIODevice::ownsFile ( ) const

inline

Returns true if the device owns the FILE pointer.

Returns: True if the device will fclose the FILE.

◆ pos()

int64_t FileIODevice::pos ( ) const

overridevirtual

Returns the current read/write position.

The default implementation returns 0.

Returns: The current position in bytes.

Reimplemented from IODevice.

◆ read()

int64_t FileIODevice::read	(	void *	data,
		int64_t	maxSize
	)

overridevirtual

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.

Implements IODevice.

◆ seek()

Error FileIODevice::seek ( int64_t pos )

overridevirtual

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 from IODevice.

◆ setFilename()

void FileIODevice::setFilename ( const String & filename )

Sets the filename for fopen-based opening.

The device must not be open when calling this.

Parameters

filename The path to the file.

◆ stderrDevice()

static FileIODevice * FileIODevice::stderrDevice ( )

static

Returns a singleton FileIODevice wrapping C stderr.

The device is a lazy-initialized static local, guaranteed to outlive any other static object that calls this function. The FILE pointer is not owned (not fclose'd).

Returns: A non-owning FileIODevice for stderr.

◆ stdinDevice()

static FileIODevice * FileIODevice::stdinDevice ( )

static

Returns a singleton FileIODevice wrapping C stdin.

The device is a lazy-initialized static local, guaranteed to outlive any other static object that calls this function. The FILE pointer is not owned (not fclose'd).

Returns: A non-owning FileIODevice for stdin.

◆ stdoutDevice()

static FileIODevice * FileIODevice::stdoutDevice ( )

static

Returns a singleton FileIODevice wrapping C stdout.

The device is a lazy-initialized static local, guaranteed to outlive any other static object that calls this function. The FILE pointer is not owned (not fclose'd).

Returns: A non-owning FileIODevice for stdout.

◆ takeFile()

FILE * FileIODevice::takeFile ( )

Transfers ownership of the FILE pointer to the caller.

After this call, the device is closed and the FILE is no longer managed by the device. The caller is responsible for fclose'ing the returned FILE.

Returns: The FILE pointer, or nullptr if the device has no FILE.

◆ write()

int64_t FileIODevice::write	(	const void *	data,
		int64_t	maxSize
	)

overridevirtual

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.

Implements IODevice.

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

include/promeki/core/fileiodevice.h

Public Types

Public Member Functions

Static Public Member Functions

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

◆ Flag

Constructor & Destructor Documentation

◆ FileIODevice() [1/3]

◆ FileIODevice() [2/3]

◆ FileIODevice() [3/3]

Member Function Documentation

◆ atEnd()

◆ close()

◆ file()

◆ filename()

◆ flush()

◆ isOpen()

◆ isSequential()

◆ open()

◆ ownsFile()

◆ pos()

◆ read()

◆ seek()

◆ setFilename()

◆ stderrDevice()

◆ stdinDevice()

◆ stdoutDevice()

◆ takeFile()

◆ write()