#include <Pt/System/FileDevice.h>

Read and write to files. More...

Public Member Functions
	FileDevice ()
	Default Constructor.

	FileDevice (const Path &path, std::ios::openmode mode)
	Construct with path to file.

	~FileDevice ()
	Destructor.

void	beginOpen (const Path &path, std::ios::openmode mode)
	Begin opening the file.

void	beginRead (char *buffer, std::size_t n)
	Begins to read data.

void	beginWrite (const char *buffer, std::size_t n)
	Begins to write data.

void	cancel ()
	Cancels all operations.

void	close ()
	Closes the device.

void	detach ()
	Remove from event loop and cancels outstanding operations.

void	endOpen ()
	End opening the file.

std::size_t	endRead ()
	Ends reading data.

std::size_t	endWrite ()
	Ends writing data.

Signal< IODevice & > &	inputReady ()
	Notifies about available data. More...

bool	isEof () const
	Returns if the device has reached EOF.

bool	isOpen () const
	Returns true if file is open.

bool	isReading () const
	Returns true if the device is reading.

bool	isWriting () const
	Returns true if the device is writing.

EventLoop *	loop () const
	Returns the used event loop.

void	open (const Path &path, std::ios::openmode mode)
	Opens the file.

Signal< FileDevice & > &	opened ()
	Notifies that the file was opened.

Signal< IODevice & > &	outputReady ()
	Notifies when data can be written. More...

std::size_t	peek (char *buffer, std::size_t n)
	Peek data from I/O device without consuming them. More...

pos_type	position ()
	Returns the current I/O position. More...

std::size_t	read (char *buffer, std::size_t n)
	Read data from I/O device. More...

bool	run ()
	Run operation if it is ready.

pos_type	seek (off_type offset, seekdir sd)
	Moves the read position to the given offset. More...

bool	seekable () const
	Returns true if device is seekable.

void	setActive (EventLoop &parent)
	Sets the parent loop, so that operations can be run.

void	setTimeout (std::size_t timeout)
	Sets the timeout for blocking I/O in milliseconds.

void	sync ()
	Synchronize device. More...

std::size_t	write (const char *buffer, std::size_t n)
	Write data to I/O device. More...

Protected Member Functions
virtual void	onAttach (EventLoop &loop)
	Attached to loop.

void	onCancel ()
	Blocks until operation has cancelled.

virtual void	onDetach (EventLoop &loop)
	Detached from loop.

virtual bool	onRun ()
	Check if ready and run.

Detailed Description

A Pt::System::FileDevice reads and writes files in the filesystem either synchronously or asynchronously. If used synchronously, it offers similar functionality like a std::fstream or the file I/O functions from the C library (fopen...). However, most applications need to perform input and output asynchronously, which makes using a FileDevice attractive. Since it inherits Pt::System::IODevice, it can be used as the endpoint of an Pt::System::IOStream or Pt::System::IOBuffer, respectively. If no buffering is required, a FileDevice can be used on its own, as shown in the following example:

void onOpen(Pt::System::FileDevice& file);
void onOutput(Pt::System::IODevice& device);
int main(int argc, char** argv)
{
    try
    {
        Pt::System::MainLoop loop;
        Pt::System::FileDevice file;
        file.setActive(loop);
        file.opened() += Pt::slot( &onOpen );
        file.outputReady() += Pt::slot( &onOutput );
        Pt::System::Path path = "tmpfile.txt";
        file.beginOpen(path, std::ios::out);
        loop.run();
        return 0;
    }
    catch(Pt::System::IOError& e)
    {
        std::cerr << "I/O error: " << e.what() << std::endl;
    }
    return -1;
}

An EventLoop is required for all asynchronous operations. This includes not only reading and writing, but also opening the file. The function beginOpen() begins to open a file and the signal returned by opened() is sent when the file was opened. It is connected to the slot shown in the next example:

void onOpen(Pt::System::FileDevice& file)
{
    file.endOpen();
    file.beginWrite("Hello world!", 12);
}

The asynchronous open operation is ended by calling endOpen(), and a write operation is started with beginWrite() to write bytes from a buffer to the file. The signal outputReady() is sent, when data was written to the file. A slot is connected to that signal to handle output:

void onOutput(Pt::System::IODevice& device)
{
    std::size_t n = device.endWrite();
    std::cout << "wrote: " << n << "bytes." << std::endl;
}

The signal is inherited from IODevice, so the signature of the slot needs a reference to a IODevice as parameter. The write operation is ended by endWrite(), which returns the number of bytes written to the file. This might be less than what was requested by beginWrite(), in which case another write operation has to be started.

All functions to begin or end asynchronous operations throw an exception of type Pt::System::IOError on failure. If IOErrors are not catched and handled in the slots, they will propagate through the EventLoop into the main() function and end the program. Normally, larger applications will need to process errors in the slots, so the EventLoop is not stopped.

Member Function Documentation

std::size_t read	(	char *	buffer,
		std::size_t	n
	)

inherited

Reads up to n bytes and stores them in buffer. Returns the number of bytes read, which may be less than requested and even 0 if the device operates in asynchronous (non-blocking) mode. In case of EOF the IODevice is set to eof.

Parameters

buffer	buffer where to place the data to be read.
n	number of bytes to read

Returns: number of bytes read, which may be less than requested.

Exceptions

IOError

std::size_t write	(	const char *	buffer,
		std::size_t	n
	)

inherited

Writes n bytes from buffer to this I/O device. Returns the number of bytes written, which may be less than requested. In case of EOF the IODevice is set to eof.

Exceptions

IOError

pos_type seek	(	off_type	offset,
		seekdir	sd
	)

inherited

Exceptions

IOError

std::size_t peek	(	char *	buffer,
		std::size_t	n
	)

inherited

void sync ( )

inherited

Commits written data to physical device.

Exceptions

IOError

pos_type position ( )

inherited

The current I/O position is returned or an IOError is thrown if the device is not seekable. Seekability can be tested with seekable().

Exceptions

IOError

Signal<IODevice&>& inputReady ( )

inherited

This signal is send when the IODevice is monitored in an EventLoop and data becomes available.

Signal<IODevice&>& outputReady ( )

inherited

This signal is send when the IODevice is monitored in an EventLoop and the device is ready to write data.

The Power in your Hands

Public Member Functions

Protected Member Functions

Detailed Description

Member Function Documentation