#include <Os/File.hpp>

Inheritance diagram for Os::FileInterface:

Public Types
enum	Mode { OPEN_NO_MODE , OPEN_READ , OPEN_CREATE , OPEN_WRITE , OPEN_SYNC_WRITE , OPEN_APPEND , MAX_OPEN_MODE }

enum	Status { OP_OK , DOESNT_EXIST , NO_SPACE , NO_PERMISSION , BAD_SIZE , NOT_OPENED , FILE_EXISTS , NOT_SUPPORTED , INVALID_MODE , INVALID_ARGUMENT , OTHER_ERROR , MAX_STATUS }

enum	OverwriteType { NO_OVERWRITE , OVERWRITE , MAX_OVERWRITE_TYPE }

enum	SeekType { RELATIVE , ABSOLUTE , MAX_SEEK_TYPE }

enum	WaitType { NO_WAIT , WAIT , MAX_WAIT_TYPE }

Public Member Functions
virtual	~FileInterface ()=default

virtual Status	open (const char *path, Mode mode, OverwriteType overwrite)=0
	open file with supplied path and mode More...

virtual void	close ()=0
	close the file, if not opened then do nothing More...

virtual Status	size (FwSignedSizeType &size_result)=0
	get size of currently open file More...

virtual Status	position (FwSignedSizeType &position_result)=0
	get file pointer position of the currently open file More...

virtual Status	preallocate (FwSignedSizeType offset, FwSignedSizeType length)=0
	pre-allocate file storage More...

virtual Status	seek (FwSignedSizeType offset, SeekType seekType)=0
	seek the file pointer to the given offset More...

virtual Status	flush ()=0
	flush file contents to storage More...

virtual Status	read (U8 *buffer, FwSignedSizeType &size, WaitType wait)=0
	read data from this file into supplied buffer bounded by size More...

virtual Status	write (const U8 *buffer, FwSignedSizeType &size, WaitType wait)=0
	read data from this file into supplied buffer bounded by size More...

virtual FileHandle *	getHandle ()=0
	returns the raw file handle More...

Static Public Member Functions
static FileInterface *	getDelegate (FileHandleStorage &aligned_placement_new_memory, const FileInterface *to_copy=nullptr)
	provide a pointer to a file delegate object More...

Detailed Description

Definition at line 17 of file File.hpp.

Member Enumeration Documentation

◆ Mode

enum Os::FileInterface::Mode

Enumerator
OPEN_NO_MODE	File mode not yet selected.
OPEN_READ	Open file for reading.
OPEN_CREATE	Open file for writing and truncates file if it exists, ie same flags as creat()
OPEN_WRITE	Open file for writing.
OPEN_SYNC_WRITE	Open file for writing; writes don't return until data is on disk.
OPEN_APPEND	Open file for appending.
MAX_OPEN_MODE	Maximum value of mode.

Definition at line 19 of file File.hpp.

◆ OverwriteType

enum Os::FileInterface::OverwriteType

Enumerator
NO_OVERWRITE	Do NOT overwrite existing files.
OVERWRITE	Overwrite file when it exists and creation was requested.
MAX_OVERWRITE_TYPE

Definition at line 44 of file File.hpp.

◆ SeekType

enum Os::FileInterface::SeekType

Enumerator
RELATIVE	Relative seek from current file offset.
ABSOLUTE	Absolute seek from beginning of file.
MAX_SEEK_TYPE

Definition at line 50 of file File.hpp.

◆ Status

enum Os::FileInterface::Status

Enumerator
OP_OK	Operation was successful.
DOESNT_EXIST	File doesn't exist (for read)
NO_SPACE	No space left.
NO_PERMISSION	No permission to read/write file.
BAD_SIZE	Invalid size parameter.
NOT_OPENED	file hasn't been opened yet
FILE_EXISTS	file already exist (for CREATE with O_EXCL enabled)
NOT_SUPPORTED	Kernel or file system does not support operation.
INVALID_MODE	Mode for file access is invalid for current operation.
INVALID_ARGUMENT	Invalid argument passed in.
OTHER_ERROR	A catch-all for other errors. Have to look in implementation-specific code.
MAX_STATUS	Maximum value of status.

Definition at line 29 of file File.hpp.

◆ WaitType

enum Os::FileInterface::WaitType

Enumerator
NO_WAIT	Do not wait for read/write operation to finish.
WAIT	Do wait for read/write operation to finish.
MAX_WAIT_TYPE

Definition at line 56 of file File.hpp.

Constructor & Destructor Documentation

◆ ~FileInterface()

virtual Os::FileInterface::~FileInterface ( )

virtualdefault

Member Function Documentation

◆ close()

virtual void Os::FileInterface::close ( )

pure virtual

close the file, if not opened then do nothing

Closes the file, if open. Otherwise this function does nothing. Delegates to the chosen implementation's closeInternal function. mode is set to OPEN_NO_MODE.

Implemented in Os::Stub::File::StubFile, Os::Posix::File::PosixFile, and Os::File.

◆ flush()

virtual Status Os::FileInterface::flush ( )

pure virtual

flush file contents to storage

Flushes the file contents to storage (i.e. out of the OS cache to disk). Does nothing in implementations that do not support flushing.

Returns: OP_OK on success otherwise error status

Implemented in Os::Stub::File::StubFile, Os::Posix::File::PosixFile, and Os::File.

◆ getDelegate()

FileInterface * Os::FileInterface::getDelegate	(	FileHandleStorage &	aligned_placement_new_memory,
		const FileInterface *	to_copy = `nullptr`
	)

static

provide a pointer to a file delegate object

get a delegate for FileInterface that intercepts calls for stub file usage

This function must return a pointer to a FileInterface object that contains the real implementation of the file functions as defined by the implementor. This function must do several things to be considered correctly implemented:

Assert that the supplied memory is non-null. e.g FW_ASSERT(aligned_placement_new_memory != NULL);
Assert that their implementation fits within FW_HANDLE_MAX_SIZE. e.g. static_assert(sizeof(PosixFileImplementation) <= sizeof Os::File::m_handle_storage, "FW_HANDLE_MAX_SIZE too small");
Assert that their implementation aligns within FW_HANDLE_ALIGNMENT. e.g. static_assert((FW_HANDLE_ALIGNMENT % alignof(PosixFileImplementation)) == 0, "Bad handle alignment");
If to_copy is null, placement new their implementation into aligned_placement_new_memory e.g. FileInterface* interface = new (aligned_placement_new_memory) PosixFileImplementation;
If to_copy is non-null, placement new using copy constructor their implementation into aligned_placement_new_memory e.g. FileInterface* interface = new (aligned_placement_new_memory) PosixFileImplementation(*to_copy);
Return the result of the placement new e.g. return interface;

Returns: result of placement new, must be equivalent to aligned_placement_new_memory

Parameters

aligned_new_memory	aligned memory to fill
to_copy	pointer to copy-constructor input

Returns: : pointer to delegate

Definition at line 14 of file DefaultFile.cpp.

◆ getHandle()

virtual FileHandle* Os::FileInterface::getHandle ( )

pure virtual

returns the raw file handle

Gets the raw file handle from the implementation. Note: users must include the implementation specific header to make any real use of this handle. Otherwise it will be as an opaque type.

Returns: raw file handle

Implemented in Os::Stub::File::StubFile, Os::Posix::File::PosixFile, and Os::File.

◆ open()

virtual Status Os::FileInterface::open	(	const char *	path,
		Mode	mode,
		OverwriteType	overwrite
	)

pure virtual

open file with supplied path and mode

Open the file passed in with the given mode. If overwrite is set to OVERWRITE, then opening files in OPEN_CREATE mode will clobber existing files. Set overwrite to NO_OVERWRITE to preserve existing files. The status of the open request is returned from the function call. Delegates to the chosen implementation's open function.

It is invalid to send nullptr as the path. It is invalid to supply mode as a non-enumerated value. It is invalid to supply overwrite as a non-enumerated value.

Parameters

path	c-string of path to open
mode	file operation mode
overwrite	overwrite existing file on create

Returns: : status of the open

Implemented in Os::Stub::File::StubFile, Os::Posix::File::PosixFile, and Os::File.

◆ position()

virtual Status Os::FileInterface::position ( FwSignedSizeType & position_result )

pure virtual

get file pointer position of the currently open file

Get the current position of the read/write pointer of the open file.

Parameters

position output parameter for size.

Returns: OP_OK on success otherwise error status

Implemented in Os::Stub::File::StubFile, Os::Posix::File::PosixFile, and Os::File.

◆ preallocate()

virtual Status Os::FileInterface::preallocate	(	FwSignedSizeType	offset,
		FwSignedSizeType	length
	)

pure virtual

pre-allocate file storage

Pre-allocates file storage with at least length storage starting at offset. No-op on implementations that cannot pre-allocate.

It is invalid to pass a negative offset. It is invalid to pass a negative length.

Parameters

offset	offset into file
length	length after offset to preallocate

Returns: OP_OK on success otherwise error status

Implemented in Os::Stub::File::StubFile, Os::Posix::File::PosixFile, and Os::File.

◆ read()

virtual Status Os::FileInterface::read	(	U8 *	buffer,
		FwSignedSizeType &	size,
		WaitType	wait
	)

pure virtual

read data from this file into supplied buffer bounded by size

Read data from this file up to the size and store it in buffer. When wait is set to WAIT, this will block until the requested size has been read successfully read or the end of the file has been reached. When wait is set to NO_WAIT it will return whatever data is currently available.

size will be updated to the count of bytes actually read. Status will reflect the success/failure of the read operation.

It is invalid to pass nullptr to this function call. It is invalid to pass a negative size. It is invalid to supply wait as a non-enumerated value.

Parameters

buffer	memory location to store data read from file
size	size of data to read
wait	`WAIT` to wait for data, `NO_WAIT` to return what is currently available

Returns: OP_OK on success otherwise error status

Implemented in Os::Stub::File::StubFile, Os::Posix::File::PosixFile, and Os::File.

◆ seek()

virtual Status Os::FileInterface::seek	(	FwSignedSizeType	offset,
		SeekType	seekType
	)

pure virtual

seek the file pointer to the given offset

Seek the file pointer to the given offset. If seekType is set to ABSOLUTE then the offset is calculated from the start of the file, and if it is set to CURRENT it is calculated from the current position.

Parameters

offset	offset to seek to
seekType	`ABSOLUTE` for seeking from beginning of file, `CURRENT` to use current position.

Returns: OP_OK on success otherwise error status

Implemented in Os::Stub::File::StubFile, Os::Posix::File::PosixFile, and Os::File.

◆ size()

virtual Status Os::FileInterface::size ( FwSignedSizeType & size_result )

pure virtual

get size of currently open file

Get the size of the currently open file and fill the size parameter. Return status of the operation.

Parameters

size	output parameter for size.

Returns: OP_OK on success otherwise error status

Implemented in Os::Stub::File::StubFile, Os::Posix::File::PosixFile, and Os::File.

◆ write()

virtual Status Os::FileInterface::write	(	const U8 *	buffer,
		FwSignedSizeType &	size,
		WaitType	wait
	)

pure virtual

read data from this file into supplied buffer bounded by size

Write data to this file up to the size from the buffer. When wait is set to WAIT, this will block until the requested size has been written successfully to disk. When wait is set to NO_WAIT it will return once the data is sent to the OS.

size will be updated to the count of bytes actually written. Status will reflect the success/failure of the read operation.

It is invalid to pass nullptr to this function call. It is invalid to pass a negative size. It is invalid to supply wait as a non-enumerated value.

Parameters

buffer	memory location to store data read from file
size	size of data to read
wait	`WAIT` to wait for data to write to disk, `NO_WAIT` to return what is currently available

Returns: OP_OK on success otherwise error status

Implemented in Os::Stub::File::StubFile, Os::Posix::File::PosixFile, and Os::File.

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

Os/File.hpp
Os/Posix/DefaultFile.cpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ Mode

◆ OverwriteType

◆ SeekType

◆ Status

◆ WaitType

Constructor & Destructor Documentation

◆ ~FileInterface()

Member Function Documentation

◆ close()

◆ flush()

◆ getDelegate()

◆ getHandle()

◆ open()

◆ position()

◆ preallocate()

◆ read()

◆ seek()

◆ size()

◆ write()