SUMMARY:  INNER | FIELD | CONSTR | METHOD | FRIEND DETAIL:  FIELD | CONSTR | METHOD | FRIEND


Platform::Io
Class File

NonCopyableType
   |
   +-File

Implemented in:
Platform.Io.File.h

class File:
private NonCopyableType

Represents a file in a filesystem.

Inner Compounds, Typedefs, and Enumscollapse
typedef Handle
          Represents the type of a system file handle.

Field Summarycollapse
protected Handle fileHandle
          Holds the system handle of this file.
protected Path filePath
          Holds the location and name of this file.

Constructor Summarycollapse
File(const Path& path, FileMode mode = FileMode_OpenOrCreate, FileAccess access = FileAccess_ReadWrite)
          Creates or opens a file.
~File()
          Closes the file and destroys this file object.

Method Summarycollapse
Long append(const Void* address, Long size) const
          Appends the specified number of bytes at a given memory address to the end of this file.
Void close()
          Closes this file.
Void flush() const
          Flushes the system caches for this file.
Handle handle() const
          Retrieves the system handle of this file.
Bool isClosed() const
          Tests whether this file has been closed.
Bool isEmpty() const
          Tests whether this file is empty, i.e.
const Path& path() const
          Retrieves the location and name of this file.
Long position() const
          Returns the current position within the file.
Long positionFromCurrent(Long distance) const
          Positions the cursor within the file relative to the current cursor position.
Long positionFromEnd(Long distance) const
          Positions the file cursor within the file relative to the end of file.
Long positionFromStart(Long distance) const
          Positions the file cursor within the file relative to the start of the file.
Long read(Void* address, Long size) const
          Reads the specified number of bytes into memory at a given address.
Long size() const
          Returns the size of this file in bytes.
Long time() const
          Returns the last modification time for this file.
Void truncate(Long size = 0) const
          Truncates the size of this file to the specified number of bytes.
Long write(const Void* address, Long size) const
          Writes the specified number of bytes at a given memory address to this file.

 

Field Detail

fileHandle

protected Handle fileHandle

Holds the system handle of this file.


filePath

protected Path filePath

Holds the location and name of this file.

 

Constructor Detail

File

File(const Path& path, FileMode mode = FileMode_OpenOrCreate, FileAccess access = FileAccess_ReadWrite)

Creates or opens a file.

Parameters:
path - the location and name of the file
mode - file open mode
access - file access mode
Throws:
InvalidFileNameException - if the specified path is invalid
FileNotFoundException - if the file cannot be found and the operation requires the file to exist
FileAlreadyExistsException - if the file already exists and the operation requires the file to not exist
AccessDeniedException - if the file is inaccessible
FileException - if the operation failed

~File[virtual]

~File()

Closes the file and destroys this file object.

 

Method Detail

append

Long append(const Void* address, Long size) const

Appends the specified number of bytes at a given memory address to the end of this file.

Parameters:
address - memory address from which to write to file
size - the number of bytes to write
Returns:
the number of bytes written to the file
Throws:
InvalidFileHandleException - if the file handle is invalid (e.g. the file already has been closed)
FileException - if the operation failed

close

Void close()

Closes this file.


flush

Void flush() const

Flushes the system caches for this file.

Throws:
InvalidFileHandleException - if the file handle is invalid (e.g. the file already has been closed)
FileException - if the operation failed

handle[inline]

Handle handle() const

Retrieves the system handle of this file.

Returns:
the system handle of this file

isClosed[nothrow]

Bool isClosed() const

Tests whether this file has been closed.

Returns:
True if this file has been closed, False otherwise

isEmpty[inline]

Bool isEmpty() const

Tests whether this file is empty, i.e. its size is zero bytes.

Returns:
True if this file is empty, False otherwise
Throws:
InvalidFileHandleException - if the file handle is invalid (e.g. the file already has been closed)
FileException - if the operation failed

path[inline]

const Path& path() const

Retrieves the location and name of this file.

Returns:
the location and name of this file

position[inline]

Long position() const

Returns the current position within the file.

Returns:
the current position within the file
Throws:
InvalidFileHandleException - if the file handle is invalid (e.g. the file already has been closed)
FileException - if the operation failed

positionFromCurrent

Long positionFromCurrent(Long distance) const

Positions the cursor within the file relative to the current cursor position. Positive distance values move the file cursor towards the end of the file, while negative distance values move the cursor towards the beginning of the file. The file cursor is always constrained within the bounds of the file such that 0 <= cursor <= file.size().

Parameters:
distance - the distance relative to the current cursor position, in bytes
Returns:
the distance travesrsed between the old and the new positions, in bytes
Throws:
InvalidFileHandleException - if the file handle is invalid (e.g. the file already has been closed)
FileException - if the operation failed

positionFromEnd

Long positionFromEnd(Long distance) const

Positions the file cursor within the file relative to the end of file. Positive distance values move the file cursor towards the end of the file, while negative distance values move the cursor towards the beginning of the file. The file cursor is always constrained within the bounds of the file such that 0 <= cursor <= file.size().

Parameters:
distance - the distance relative to the end of the file, in bytes
Returns:
the distance travesrsed between the old and the new positions, in bytes
Throws:
InvalidFileHandleException - if the file handle is invalid (e.g. the file already has been closed)
FileException - if the operation failed

positionFromStart

Long positionFromStart(Long distance) const

Positions the file cursor within the file relative to the start of the file. Positive distance values move the file cursor towards the end of the file, while negative distance values move the cursor towards the beginning of the file. The file cursor is always constrained within the bounds of the file such that 0 <= cursor <= file.size().

Parameters:
distance - the distance relative to the beginning of the file, in bytes
Returns:
the distance travesrsed between the old and the new positions, in bytes
Throws:
InvalidFileHandleException - if the file handle is invalid (e.g. the file already has been closed)
FileException - if the operation failed

read

Long read(Void* address, Long size) const

Reads the specified number of bytes into memory at a given address.

Parameters:
address - memory to read file into
size - the number of bytes to read
Returns:
the number of bytes read from the file
Throws:
InvalidFileHandleException - if the file handle is invalid (e.g. the file already has been closed)
FileException - if the operation failed

size

Long size() const

Returns the size of this file in bytes.

Returns:
the size of this file in bytes
Throws:
InvalidFileHandleException - if the file handle is invalid (e.g. the file already has been closed)
FileException - if the operation failed

time

Long time() const

Returns the last modification time for this file.

Returns:
the last modification time for this file
Throws:
InvalidFileHandleException - if the file handle is invalid (e.g. the file already has been closed)
FileException - if the operation failed

truncate

Void truncate(Long size = 0) const

Truncates the size of this file to the specified number of bytes.

Parameters:
size - the desired size of file in bytes
Throws:
InvalidFileHandleException - if the file handle is invalid (e.g. the file already has been closed)
FileException - if the operation failed

write

Long write(const Void* address, Long size) const

Writes the specified number of bytes at a given memory address to this file.

Parameters:
address - memory address from which to write to file
size - the number of bytes to write
Returns:
the number of bytes written to the file
Throws:
InvalidFileHandleException - if the file handle is invalid (e.g. the file already has been closed)
FileException - if the operation failed


SUMMARY:  INNER | FIELD | CONSTR | METHOD | FRIEND DETAIL:  FIELD | CONSTR | METHOD | FRIEND