#include <Os/File.hpp>

Inheritance diagram for Os::File:

Public Member Functions
	File ()
	constructor More...

	~File () final
	destructor More...

	File (const File &other)
	copy constructor that copies the internal representation More...

File &	operator= (const File &other)
	assignment operator that copies the internal representation More...

bool	isOpen () const
	determine if the file is open More...

Os::FileInterface::Status	open (const char *path, Mode mode)
	open file with supplied path and mode More...

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

Status	write (const U8 *buffer, FwSignedSizeType &size)
	write data to this file from the supplied buffer bounded by size More...

Os::FileInterface::Status	open (const char *path, Mode mode, OverwriteType overwrite) override
	open file with supplied path and mode More...

void	close () override
	close the file, if not opened then do nothing More...

Status	size (FwSignedSizeType &size_result) override
	get size of currently open file More...

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

Status	preallocate (FwSignedSizeType offset, FwSignedSizeType length) override
	pre-allocate file storage More...

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

Status	flush () override
	flush file contents to storage More...

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

Status	readline (U8 *buffer, FwSignedSizeType &size, WaitType wait)
	read a line from the file using `\n` as the delimiter More...

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

FileHandle *	getHandle () override
	returns the raw file handle More...

Status	calculateCrc (U32 &crc)
	calculate the CRC32 of the entire file More...

Status	incrementalCrc (FwSignedSizeType &size)
	calculate the CRC32 of the next section of data More...

Status	finalizeCrc (U32 &crc)
	finalize and retrieve the CRC value More...

Public Member Functions inherited from Os::FileInterface
virtual	~FileInterface ()=default

Additional Inherited Members
Public Types inherited from Os::FileInterface
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 }

Static Public Member Functions inherited from Os::FileInterface
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 214 of file File.hpp.

Constructor & Destructor Documentation

◆ File() [1/2]

Os::File::File ( )

constructor

Definition at line 13 of file File.cpp.

◆ ~File()

Os::File::~File ( )

final

destructor

Destructor closes the file if it is open

Definition at line 17 of file File.cpp.

◆ File() [2/2]

Os::File::File ( const File & other )

copy constructor that copies the internal representation

Definition at line 25 of file File.cpp.

Member Function Documentation

◆ calculateCrc()

File::Status Os::File::calculateCrc ( U32 & crc )

calculate the CRC32 of the entire file

Calculates the CRC32 of the file's contents. The crc parameter will be updated to contain the CRC or 0 on failure. Status will represent failure conditions. This call will be decomposed into calculations on sections of the file FW_FILE_CHUNK_SIZE bytes long.

This function requires that the file already be opened for "READ" mode.

On error crc will be set to 0.

This function is equivalent to the following pseudo-code:

U32 crc;
do {
    size = FW_FILE_CHUNK_SIZE;
    m_file.incrementalCrc(size);
while (size == FW_FILE_CHUNK_SIZE);
m_file.finalize(crc);

Parameters

crc	U32 bit value to fill with CRC

Returns: OP_OK on success otherwise error status

Definition at line 189 of file File.cpp.

◆ close()

void Os::File::close ( )

overridevirtual

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.

Implements Os::FileInterface.

Definition at line 70 of file File.cpp.

◆ finalizeCrc()

File::Status Os::File::finalizeCrc ( U32 & crc )

finalize and retrieve the CRC value

Finalizes the CRC computation and returns the CRC value. The crc value will be modified to contain the crc or 0 on error. Note: this will reset any active CRC calculation and effectively re-initializes any incrementalCrc calculation.

On error crc will be set to 0.

Parameters

crc	value to fill

Returns: status of the CRC calculation

Definition at line 230 of file File.cpp.

◆ flush()

File::Status Os::File::flush ( )

overridevirtual

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

Implements Os::FileInterface.

Definition at line 131 of file File.cpp.

◆ getHandle()

FileHandle * Os::File::getHandle ( )

overridevirtual

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//!must* be passed as an opaque type.

Returns: raw file handle

Implements Os::FileInterface.

Definition at line 184 of file File.cpp.

◆ incrementalCrc()

File::Status Os::File::incrementalCrc ( FwSignedSizeType & size )

calculate the CRC32 of the next section of data

Starting at the current file pointer, this will add size bytes of data to the currently calculated CRC. Call finalizeCrc to retrieve the CRC or calculateCrc to perform a CRC on the entire file. This call will not block waiting for data on the underlying read, nor will it reset the file position pointer. On error, the current CRC results should be discarded by reopening the file or calling finalizeCrc and discarding its result. size will be updated with the size actually read and used in the CRC calculation.

This function requires that the file already be opened for "READ" mode.

It is illegal for size to be less than or equal to 0 or greater than FW_FILE_CHUNK_SIZE.

Parameters

size	size of data to read for CRC

Returns: : status of the CRC calculation

Definition at line 207 of file File.cpp.

◆ isOpen()

bool Os::File::isOpen ( ) const

determine if the file is open

Returns: true if file is open, false otherwise

Definition at line 79 of file File.cpp.

◆ open() [1/2]

File::Status Os::File::open	(	const char *	path,
		File::Mode	requested_mode
	)

open file with supplied path and mode

Open the file passed in with the given mode. Opening files with OPEN_CREATE mode will not clobber existing files. Use other open method to set overwrite flag and clobber 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.

Parameters

path	c-string of path to open
mode	file operation mode

Returns: : status of the open

Definition at line 45 of file File.cpp.

◆ open() [2/2]

File::Status Os::File::open	(	const char *	path,
		File::Mode	requested_mode,
		File::OverwriteType	overwrite
	)

overridevirtual

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

Implements Os::FileInterface.

Definition at line 49 of file File.cpp.

◆ operator=()

File & Os::File::operator= ( const File & other )

assignment operator that copies the internal representation

Definition at line 35 of file File.cpp.

◆ position()

File::Status Os::File::position ( FwSignedSizeType & position_result )

overridevirtual

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

Implements Os::FileInterface.

Definition at line 94 of file File.cpp.

◆ preallocate()

File::Status Os::File::preallocate	(	FwSignedSizeType	offset,
		FwSignedSizeType	length
	)

overridevirtual

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

Implements Os::FileInterface.

Definition at line 104 of file File.cpp.

◆ read() [1/2]

File::Status Os::File::read	(	U8 *	buffer,
		FwSignedSizeType &	size
	)

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. This version will will block until the requested size has been read successfully read or the end of the file has been reached.

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.

Parameters

buffer	memory location to store data read from file
size	size of data to read

Returns: OP_OK on success otherwise error status

Definition at line 143 of file File.cpp.

◆ read() [2/2]

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

overridevirtual

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

Implements Os::FileInterface.

Definition at line 147 of file File.cpp.

◆ readline()

File::Status Os::File::readline	(	U8 *	buffer,
		FwSignedSizeType &	size,
		File::WaitType	wait
	)

read a line from the file using \n as the delimiter

Reads a single line from the file including the terminating '
'. This will return an error if no line is found within the specified buffer size. In the case of EOF, the line is read without the terminating '
'.

In the case of an error, this function will seek to the original location in the file. Otherwise, the pointer will point to the first character after the \n or EOF in the case of no \n.

It is invalid to send a null buffer. It is invalid to send a size less than 0. It is an error if the file is not opened for reading.

Parameters

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

Returns: OP_OK on success otherwise error status

Definition at line 237 of file File.cpp.

◆ seek()

File::Status Os::File::seek	(	FwSignedSizeType	offset,
		File::SeekType	seekType
	)

overridevirtual

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

Implements Os::FileInterface.

Definition at line 118 of file File.cpp.

◆ size()

File::Status Os::File::size ( FwSignedSizeType & size_result )

overridevirtual

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

Implements Os::FileInterface.

Definition at line 85 of file File.cpp.

◆ write() [1/2]

File::Status Os::File::write	(	const U8 *	buffer,
		FwSignedSizeType &	size
	)

write data to this file from the supplied buffer bounded by size

Write data from buffer up to the size and store it in this file. This call will block until the requested size has been written. Otherwise, this call will write without blocking.

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

It is invalid to pass nullptr to this function call. It is invalid to pass a negative size.

Parameters

buffer	memory location of data to write to file
size	size of data to write

Returns: OP_OK on success otherwise error status

Definition at line 163 of file File.cpp.

◆ write() [2/2]

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

overridevirtual

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

Implements Os::FileInterface.

Definition at line 168 of file File.cpp.

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

Os/File.hpp
Os/File.cpp

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ File() [1/2]

◆ ~File()

◆ File() [2/2]

Member Function Documentation

◆ calculateCrc()

◆ close()

◆ finalizeCrc()

◆ flush()

◆ getHandle()

◆ incrementalCrc()

◆ isOpen()

◆ open() [1/2]

◆ open() [2/2]

◆ operator=()

◆ position()

◆ preallocate()

◆ read() [1/2]

◆ read() [2/2]

◆ readline()

◆ seek()

◆ size()

◆ write() [1/2]

◆ write() [2/2]