A temporary file that may optionally "shadow" another file. More...

#include <TempFile.h++>

Inheritance diagram for TempFile:

Collaboration diagram for TempFile:

Public Member Functions
	TempFile (const String &path=String::null)
	Construct a new TempFile. More...

	~TempFile ()
	Destructor. More...

void	open ()
	Create and open the TempFile. More...

virtual void	close ()
	Close (and delete) the temporary file. More...

virtual size_t	read (ByteBuffer &buffer)
	Read data from the stream into a ByteBuffer. More...

virtual size_t	read (CharBuffer &buffer)
	Read data from the stream into a CharBuffer. More...

template<typename T >
size_t	read (Buffer< T > &buffer, size_t &partial)
	Read data from the stream into a Buffer of arbitrary type. More...

virtual size_t	read (byte_t *buffer, size_t buflen)
	Read data from the stream into a raw buffer. More...

size_t	read (byte_t *buffer, size_t buflen, int64_t offset, AsyncIOTask &task)
	Read data asynchronously from the stream into a raw buffer. More...

size_t	read (ByteBuffer &buffer, int64_t offset, AsyncIOTask &task)
	Read data asynchronously from the stream into a Buffer. More...

virtual size_t	read (MemoryBlock *vec, uint_t count)
	Read data from the stream into a series of I/O buffers. More...

size_t	write (const byte_t *buffer, size_t buflen, int64_t offset, AsyncIOTask &task)
	Write data asynchronously to the stream from a raw buffer. More...

size_t	write (ByteBuffer &buffer, int64_t offset, AsyncIOTask &task)
	Write data asynchronously to the stream from a Buffer. More...

virtual size_t	write (ByteBuffer &buffer)
	Write data to the stream from a ByteBuffer. More...

virtual size_t	write (CharBuffer &buffer)
	Write data to the stream from a CharBuffer. More...

template<typename T >
size_t	write (Buffer< T > &buffer, size_t &partial)
	Write data to the stream from a Buffer of arbitrary type. More...

virtual size_t	write (const byte_t *buffer, size_t buflen)
	Write data to the stream from a raw buffer, until either the entire buffer is written or an error or timeout occurs. More...

virtual size_t	write (const MemoryBlock *vec, uint_t count)
	Write data to the stream from a series of I/O buffers. More...

virtual size_t	readFully (ByteBuffer &buffer, size_t count=0)
	Read data from the stream into a ByteBuffer, until either the buffer is full or an error or timeout occurs. More...

virtual size_t	readFully (CharBuffer &buffer, size_t count=0)
	Read data from the stream into a CharBuffer, until either the buffer is full or an error or timeout occurs. More...

template<typename T >
size_t	readFully (Buffer< T > &buffer, size_t &partial)
	Read data from the stream into a Buffer of arbitrary type, until either the buffer is full or an error or timeout occurs. More...

virtual size_t	readFully (byte_t *buffer, size_t buflen)
	Read data from the stream into a raw buffer, until either the buffer is full or an error or timeout occurs. More...

virtual size_t	writeFully (ByteBuffer &buffer)
	Write data to the stream from a ByteBuffer, until either the entire buffer is written or an error or timeout occurs. More...

virtual size_t	writeFully (CharBuffer &buffer)
	Write data to the stream from a CharBuffer, until either the entire buffer is written or an error or timeout occurs. More...

template<typename T >
size_t	writeFully (Buffer< T > &buffer, size_t &partial)
	Write data to the stream from a Buffer of arbitrary type, until either the entire buffer is written or an error or timeout occurs. More...

virtual size_t	writeFully (const byte_t *buffer, size_t buflen)
	Write data to the stream from a raw buffer. More...

virtual int64_t	seek (int64_t offset, SeekMode mode=SeekAbsolute)
	Reposition the seek pointer in the stream. More...

virtual int64_t	tell ()
	Get the current (absolute) offset of the seek pointer. More...

bool	isOpen () const
	Test if the stream is open. More...

bool	isSeekable () const
	Test if the stream supports seeking. More...

bool	isReadable () const
	Test if the stream can be read from. More...

bool	isWritable () const
	Test if the stream can be written to. More...

bool	isFullDuplex () const
	Test if the stream is full-duplex (i.e., supports both reading and writing). More...

bool	isHalfDuplex () const
	Test if the stream is half-duplex (i.e., supports either reading or writing, but not both). More...

virtual void	close (IOMode mode=IOReadWrite)
	Close the stream for reading, writing, or both. More...

virtual void	setTimeout (timespan_ms_t timeout)
	Set the stream I/O timeout, in milliseconds. More...

timespan_ms_t	getTimeout () const
	Get the stream I/O timeout, in milliseconds. More...

Static Public Attributes
static const uint_t	MAX_IOBLOCK_COUNT = 16
	The maximum number of I/O buffers that can be passed to the vector I/O methods. More...

Protected Member Functions
void	_init (FileHandle handle, bool seekable, bool readable, bool writable)
	Initialize the stream for use with an open file. More...

Detailed Description

A temporary file that may optionally "shadow" another file.

If constructed with a path, the temporary file will be created in the same directory as the file specified by that path; when the temporary file is closed, it will be atomically moved onto the original file. This is useful for safely updating an existing file.

If constructed without a path, the temporary file will be created in the host platform's designated temporary directory; when the file is closed, it will be deleted.

Author: Mark Lindner

Constructor & Destructor Documentation

◆ TempFile()

TempFile ( const String & path = String::null )

Construct a new TempFile.

Parameters

path	The path to the file being shadowed, if any.

◆ ~TempFile()

~TempFile ( )

Destructor.

Member Function Documentation

◆ _init()

void _init	(	FileHandle	handle,
		bool	seekable,
		bool	readable,
		bool	writable
	)

protectedinherited

Initialize the stream for use with an open file.

Parameters

handle	The handle to an open file.
seekable	A flag indicating whether the stream is seekable.
readable	A flag indicating whether the stream is readable.
writable	A flag indicating whether the stream is writable.

◆ close() [1/2]

void close ( )

virtual

Close (and delete) the temporary file.

If the temporary file is shadowing another file, its contents are copied to that file before the temporary file is deleted.

◆ close() [2/2]

void close ( IOMode mode = IOReadWrite )

virtualinherited

Close the stream for reading, writing, or both.

Parameters

mode	The close mode.

Reimplemented in StreamSocket, and StreamPipe.

◆ getTimeout()

timespan_ms_t getTimeout ( ) const

inlineinherited

Get the stream I/O timeout, in milliseconds.

◆ isFullDuplex()

bool isFullDuplex ( ) const

inlineinherited

Test if the stream is full-duplex (i.e., supports both reading and writing).

◆ isHalfDuplex()

bool isHalfDuplex ( ) const

inlineinherited

Test if the stream is half-duplex (i.e., supports either reading or writing, but not both).

◆ isOpen()

bool isOpen ( ) const

inlineinherited

Test if the stream is open.

◆ isReadable()

bool isReadable ( ) const

inlineinherited

Test if the stream can be read from.

◆ isSeekable()

bool isSeekable ( ) const

inlineinherited

Test if the stream supports seeking.

◆ isWritable()

bool isWritable ( ) const

inlineinherited

Test if the stream can be written to.

◆ open()

void open ( )

Create and open the TempFile.

Exceptions

IOException If the file could not be created and/or opened.

◆ read() [1/7]

size_t read ( ByteBuffer & buffer )

virtualinherited

Read data from the stream into a ByteBuffer.

Parameters

buffer The buffer to read into.

Returns: The number of bytes actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

Reimplemented in StreamSocket.

◆ read() [2/7]

size_t read ( CharBuffer & buffer )

virtualinherited

Read data from the stream into a CharBuffer.

Parameters

buffer The buffer to read into.

Returns: The number of characters actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

Reimplemented in StreamSocket.

◆ read() [3/7]

size_t read	(	Buffer< T > &	buffer,
		size_t &	partial
	)

inlineinherited

Read data from the stream into a Buffer of arbitrary type.

If sizeof(T) is greater than 1 byte, then there can be no guarantee that the number of bytes read before a timeout or error occurs will be evenly divisible by sizeof(T). If the final element was partially read, the number of bytes of the element that were read will be stored in partial; this value should be passed unmodified to the next invocation of this method to continue reading from the appropriate offset within the partially-read element.

Parameters

buffer	The buffer to read into.
partial	The number of bytes remaining to read for a partially-read element; on return, the number of bytes read of a partially-read element, or 0 if the last element was read completely. Should be set to 0 prior to the first call to this method for a fresh buffer.

Returns: The number of whole elements actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

◆ read() [4/7]

size_t read	(	byte_t *	buffer,
		size_t	buflen
	)

virtualinherited

Read data from the stream into a raw buffer.

Parameters

buffer	The buffer to read into.
buflen	The number of bytes to read.

Returns: The number of bytes actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

Reimplemented in StreamSocket.

◆ read() [5/7]

size_t read	(	byte_t *	buffer,
		size_t	buflen,
		int64_t	offset,
		AsyncIOTask &	task
	)

inherited

Read data asynchronously from the stream into a raw buffer.

Parameters

buffer	The buffer to read into.
buflen	The number of bytes to read.
offset	The file offset to read from.
task	The async I/O control block for monitoring the operation.

Returns: The number of bytes actually read, if the operation completed immediately, otherwise 0 to indicate that the operation has begun.

Exceptions

IOException If an I/O error occurred.

◆ read() [6/7]

size_t read	(	ByteBuffer &	buffer,
		int64_t	offset,
		AsyncIOTask &	task
	)

inherited

Read data asynchronously from the stream into a Buffer.

Parameters

buffer	The Buffer to read into. This object must not be destroyed before the asynchronous I/O operation is completed or cancelled.
offset	The file offset to read from.
task	The async I/O control block for monitoring the operation.

Returns: The number of bytes actually read, if the operation completed immediately, otherwise 0 to indicate that the operation has begun.

Exceptions

IOException If an I/O error occurred.

◆ read() [7/7]

size_t read	(	MemoryBlock *	vec,
		uint_t	count
	)

virtualinherited

Read data from the stream into a series of I/O buffers.

This operation is known as "vector read" or "scatter read." The buffers are read into in order. On systems that support it, the operation is performed with a single system call.

Parameters

vec	An array of buffers to read into.
count	The number of buffers in the array.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

Reimplemented in StreamSocket.

◆ readFully() [1/4]

size_t readFully	(	ByteBuffer &	buffer,
		size_t	count = `0`
	)

virtualinherited

Read data from the stream into a ByteBuffer, until either the buffer is full or an error or timeout occurs.

Parameters

buffer	The buffer to read into.
count	The number of bytes to read. If 0 or greater than the number of bytes between the position and the limit, reads up to the limit.

Returns: The number of bytes actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

◆ readFully() [2/4]

size_t readFully	(	CharBuffer &	buffer,
		size_t	count = `0`
	)

virtualinherited

Read data from the stream into a CharBuffer, until either the buffer is full or an error or timeout occurs.

Parameters

buffer	The buffer to read into.
count	The number of characters to read. If 0 or greater than the number of bytes between the position and the limit, reads up to the limit.

Returns: The number of bytes actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

◆ readFully() [3/4]

size_t readFully	(	Buffer< T > &	buffer,
		size_t &	partial
	)

inlineinherited

Read data from the stream into a Buffer of arbitrary type, until either the buffer is full or an error or timeout occurs.

If sizeof(T) is greater than 1 byte, then there can be no guarantee that the number of bytes read before a timeout or error occurs will be evenly divisible by sizeof(T). If the final element was partially read, the number of bytes of the element that were read will be stored in partial; this value should be passed unmodified to the next invocation of this method to continue reading from the appropriate offset within the partially-read element.

Parameters

buffer	The buffer to read into.
partial	The number of bytes remaining to read for a partially-read element; on return, the number of bytes read of a partially-read element, or 0 if the last element was read completely. Should be set to 0 prior to the first call to this method for a fresh buffer.

Returns: The number of whole elements actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

◆ readFully() [4/4]

size_t readFully	(	byte_t *	buffer,
		size_t	buflen
	)

virtualinherited

Read data from the stream into a raw buffer, until either the buffer is full or an error or timeout occurs.

Parameters

buffer	The buffer to read into.
buflen	The number of bytes to read.

Returns: The number of bytes actually read.

Exceptions

IOException If the end-of-file was reached or some other I/O error occurred.

◆ seek()

int64_t seek	(	int64_t	offset,
		SeekMode	mode = `SeekAbsolute`
	)

virtualinherited

Reposition the seek pointer in the stream.

Parameters

offset	The new offset.
mode	The seek mode.

Returns: The new position of the seek pointer.

Exceptions

IOException If the stream does not support seeking, or if some other I/O error occurred.

◆ setTimeout()

void setTimeout ( timespan_ms_t timeout )

virtualinherited

Set the stream I/O timeout, in milliseconds.

A timeout of 0 indicates no timeout, and a timeout of -1 indicates infinite timeout (blocking I/O).

Reimplemented in StreamSocket, and SerialPort.

◆ tell()

int64_t tell ( )

virtualinherited

Get the current (absolute) offset of the seek pointer.

Returns: The current offset, from the beginning of the stream.

Exceptions

IOException If the stream does not support seeking, or if some other I/O error occurred.

◆ write() [1/7]

size_t write	(	const byte_t *	buffer,
		size_t	buflen,
		int64_t	offset,
		AsyncIOTask &	task
	)

inherited

Write data asynchronously to the stream from a raw buffer.

Parameters

buffer	The buffer to write.
buflen	The number of bytes to write.
offset	The file offset to write to.
task	The async I/O control block for monitoring the operation.

Returns: The number of bytes actually written, if the operation completed immediately, otherwise 0 to indicate that the operation has begun.

Exceptions

IOException If an I/O error occurred.

◆ write() [2/7]

size_t write	(	ByteBuffer &	buffer,
		int64_t	offset,
		AsyncIOTask &	task
	)

inherited

Write data asynchronously to the stream from a Buffer.

Parameters

buffer	The Buffer to write. This object must not be destroyed before the asynchronous I/O operation is completed or cancelled.
offset	The file offset to write to.
task	The async I/O control block for monitoring the operation.

Returns: The number of bytes actually written, if the operation completed immediately, otherwise 0 to indicate that the operation has begun.

Exceptions

IOException If an I/O error occurred.

◆ write() [3/7]

size_t write ( ByteBuffer & buffer )

virtualinherited

Write data to the stream from a ByteBuffer.

Parameters

buffer The buffer to write.

Returns: The number of bytes actually written.

Exceptions

IOException If an I/O error occurred.

Reimplemented in StreamSocket.

◆ write() [4/7]

size_t write ( CharBuffer & buffer )

virtualinherited

Write data to the stream from a CharBuffer.

Parameters

buffer The buffer to write.

Returns: The number of characters actually written.

Exceptions

IOException If an I/O error occurred.

Reimplemented in StreamSocket.

◆ write() [5/7]

size_t write	(	Buffer< T > &	buffer,
		size_t &	partial
	)

inlineinherited

Write data to the stream from a Buffer of arbitrary type.

If sizeof(T) is greater than 1 byte, then there can be no guarantee that the number of bytes written before a timeout or error occurs will be evenly divisible by sizeof(T). If the final element was partially written, the number of bytes of the element that were written will be stored in partial; this value should be passed unmodified to the next invocation of this method to continue writing from the appropriate offset within the partially-written element.

Parameters

buffer	The buffer to write.
partial	The number of bytes remaining to write for a partially-written element; on return, the number of bytes written of a partially-written element, or 0 if the last element was written completely. Should be set to 0 prior to the first call to this method for a fresh buffer.

Returns: The number of whole elements actually written.

Exceptions

IOException If an I/O error occurred.

◆ write() [6/7]

size_t write	(	const byte_t *	buffer,
		size_t	buflen
	)

virtualinherited

Write data to the stream from a raw buffer, until either the entire buffer is written or an error or timeout occurs.

Parameters

buffer	A pointer to the buffer.
buflen	The number of bytes to write.

Returns: The number of bytes actually written.

Exceptions

IOException If an I/O error occurred.

Reimplemented in StreamSocket.

◆ write() [7/7]

size_t write	(	const MemoryBlock *	vec,
		uint_t	count
	)

virtualinherited

Write data to the stream from a series of I/O buffers.

This operation is known as "vector write" or "gather write." The buffers are written in order. On systems that support it, the operation is performed with a single system call.

Parameters

vec	An array of buffers to write.
count	The number of buffers in the array.

Exceptions

IOException If an I/O error occurred.

Reimplemented in StreamSocket.

◆ writeFully() [1/4]

size_t writeFully ( ByteBuffer & buffer )

virtualinherited

Write data to the stream from a ByteBuffer, until either the entire buffer is written or an error or timeout occurs.

Parameters

buffer The buffer to write.

Returns: The number of bytes actually written.

Exceptions

IOException If and I/O error occurred.

◆ writeFully() [2/4]

size_t writeFully ( CharBuffer & buffer )

virtualinherited

Write data to the stream from a CharBuffer, until either the entire buffer is written or an error or timeout occurs.

Parameters

buffer The buffer to write.

Returns: The number of bytes actually written.

Exceptions

IOException If an I/O error occurred.

◆ writeFully() [3/4]

size_t writeFully	(	Buffer< T > &	buffer,
		size_t &	partial
	)

inlineinherited

Write data to the stream from a Buffer of arbitrary type, until either the entire buffer is written or an error or timeout occurs.

If sizeof(T) is greater than 1 byte, then there can be no guarantee that the number of bytes written before a timeout or error occurs will be evenly divisible by sizeof(T). If the final element was partially written, the number of bytes of the element that were written will be stored in partial; this value should be passed unmodified to the next invocation of this method to continue writing from the appropriate offset within the partially-written element.

Parameters

buffer	The buffer to write.
partial	The number of bytes remaining to write for a partially-written element; on return, the number of bytes written of a partially-written element, or 0 if the last element was written completely. Should be set to 0 prior to the first call to this method for a fresh buffer.

Returns: The number of whole elements actually written.

Exceptions

IOException If an I/O error occurred.

◆ writeFully() [4/4]

size_t writeFully	(	const byte_t *	buffer,
		size_t	buflen
	)

virtualinherited

Write data to the stream from a raw buffer.

Parameters

buffer	A pointer to the buffer.
buflen	The number of bytes to write.

Returns: The number of bytes actually written.

Exceptions

IOException If an I/O error occurred.

Member Data Documentation

◆ MAX_IOBLOCK_COUNT

const uint_t MAX_IOBLOCK_COUNT = 16

staticinherited

The maximum number of I/O buffers that can be passed to the vector I/O methods.

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

Public Member Functions

Static Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ TempFile()

◆ ~TempFile()

Member Function Documentation

◆ _init()

◆ close() [1/2]

◆ close() [2/2]

◆ getTimeout()

◆ isFullDuplex()

◆ isHalfDuplex()

◆ isOpen()

◆ isReadable()

◆ isSeekable()

◆ isWritable()

◆ open()

◆ read() [1/7]

◆ read() [2/7]

◆ read() [3/7]

◆ read() [4/7]

◆ read() [5/7]

◆ read() [6/7]

◆ read() [7/7]

◆ readFully() [1/4]

◆ readFully() [2/4]

◆ readFully() [3/4]

◆ readFully() [4/4]

◆ seek()

◆ setTimeout()

◆ tell()

◆ write() [1/7]

◆ write() [2/7]

◆ write() [3/7]

◆ write() [4/7]

◆ write() [5/7]

◆ write() [6/7]

◆ write() [7/7]

◆ writeFully() [1/4]

◆ writeFully() [2/4]

◆ writeFully() [3/4]

◆ writeFully() [4/4]

Member Data Documentation

◆ MAX_IOBLOCK_COUNT