System file reference class. More...

Collaboration diagram for Burger::File:

[legend]

Public Types
enum	eFileAccess { kReadOnly , kWriteOnly , kAppend , kReadWrite }
	Enumeration to open a file. More...

Public Member Functions
	File () noexcept
	Create a File class.

	File (const char *pFileName, eFileAccess uAccess=kReadOnly) noexcept
	Create a File class with a file.

	File (Filename *pFileName, eFileAccess uAccess=kReadOnly) noexcept
	Create a File class with a Filename.

	~File ()
	Close any open file.

Filename *	get_filename (void) noexcept
	Return Filename object.

void *	get_file_pointer (void) const noexcept
	Return the native file reference.

void	set_file_pointer (void *pFile) noexcept
	Set the native file reference.

uint_t	is_opened (void) const noexcept
	Return TRUE if a file is open.

eError	open (const char *pFileName, eFileAccess uAccess=kReadOnly) noexcept
	Open a file using a Burgerlib pathname.

eError	open (Filename *pFileName, eFileAccess uAccess=kReadOnly) noexcept
	Open a file using a Filename.

eError	open_async (const char *pFileName, eFileAccess uAccess=kReadOnly) noexcept
	Open a file asynchronously.

eError	open_async (Filename *pFileName, eFileAccess uAccess=kReadOnly) noexcept
	Open a file asynchronously.

eError	close (void) noexcept
	Close open file.

eError	close_async (void) noexcept
	Close open file asynchronously.

uint64_t	get_file_size (void) noexcept
	Return the size of a file in bytes.

uintptr_t	read (void *pOutput, uintptr_t uSize) noexcept
	Read data from an open file.

eError	read_async (void *pOutput, uintptr_t uSize) noexcept
	Read open file asynchronously.

uintptr_t	write (const void *pInput, uintptr_t uSize) noexcept
	Write data into an open file.

uint64_t	get_mark (void) noexcept
	Get the current file mark.

eError	set_mark (uint64_t uMark) noexcept
	Set the current file mark.

eError	set_mark_at_EOF (void) noexcept
	Set the current file mark at the end of the file.

eError	get_modification_time (TimeDate_t *pOutput) noexcept
	Get the time the file was last modified.

eError	get_creation_time (TimeDate_t *pOutput) noexcept
	Get the time the file was created.

eError	set_modification_time (const TimeDate_t *pInput) noexcept
	Set the time the file was last modified.

eError	set_creation_time (const TimeDate_t *pInput) noexcept
	Set the time the file was created.

eError	set_creator_type (uint32_t uCreatorType) noexcept
	Set the file's auxiliary type.

eError	set_file_type (uint32_t uFileType) noexcept
	Set the file's type code.

uint32_t	get_creator_type (void) noexcept
	Get the file's auxiliary type.

uint32_t	get_file_type (void) noexcept
	Get the file's type code.

eError	set_creator_and_file_type (uint32_t uCreatorType, uint32_t uFileType) noexcept
	Set the file's auxiliary and file type.

eError	read_c_string (char *pOutput, uintptr_t uLength) noexcept
	Read a "C" string with the terminating zero to a file stream.

uint32_t	read_big_uint32 (void) noexcept
	Read a big endian 32-bit value from a file.

uint16_t	read_big_uint16 (void) noexcept
	Read a big endian 16-bit value from a file.

uint32_t	read_little_uint32 (void) noexcept
	Read a little endian 32-bit value from a file.

uint16_t	read_little_uint16 (void) noexcept
	Read a little endian 16-bit value from a file.

Static Public Member Functions
static File *	New (const char *pFileName, eFileAccess uAccess=kReadOnly) noexcept
	Create a new File instance.

static File *	New (Filename *pFileName, eFileAccess uAccess=kReadOnly) noexcept
	Create a new File instance.

Protected Attributes
void *	m_pFile
	Open file reference.

Filename	m_Filename
	Name of the file that was opened.

uint_t	m_bUsingFSRef
	True if using MacOS 9 or higher APIs (MacOS Only)

Private Member Functions
	File (const File &)=delete

File &	operator= (const File &)=delete

	File (File &&)=delete

File &	operator= (File &&)=delete

Detailed Description

System file reference class.

A functional equivalent to FILE *, except files are all considered binary and pathnames are only Burgerlib format.

See also: FileManager or Filename

Member Enumeration Documentation

◆ eFileAccess

enum Burger::File::eFileAccess

Enumeration to open a file.

Used by open(const char*, eFileAccess) to determine the method of opening a file.

See also: open(const char*, eFileAccess) or open(Filename*, eFileAccess)

Enumerator
kReadOnly	Open file with read access only.
kWriteOnly	Create and open empty file with write access only.
kAppend	Open file with write access and set the mark at the end.
kReadWrite	Open file for read and write access.

Constructor & Destructor Documentation

◆ File() [1/5]

Burger::File::File ( const File & )

privatedelete

◆ File() [2/5]

Burger::File::File ( File && )

privatedelete

◆ File() [3/5]

Burger::File::File ( )

noexcept

Create a File class.

Initialize variables, however no file is opened so all file access functions will fail until open() is called and it succeeds.

See also: open(const char*, eFileAccess), open(Filename*, eFileAccess), close(), ~File()

◆ File() [4/5]

Burger::File::File	(	const char *	pFileName,
		eFileAccess	uAccess = kReadOnly )

noexcept

Create a File class with a file.

Open a file and initialize the variables. If the file open operation fails, all file access functions will fail until a new file is opened.

Use is_opened() const to test if the file successfully opened.

Parameters

pFileName	Pointer to a "C" string containing a Burgerlib pathname
uAccess	Enumeration on permissions requested on the opened file

See also: open(const char*, eFileAccess), File(Filename*, eFileAccess), close()

◆ File() [5/5]

Burger::File::File	(	Filename *	pFileName,
		eFileAccess	uAccess = kReadOnly )

noexcept

Create a File class with a Filename.

Open a file and initialize the variables. If the file open operation fails, all file access functions will fail until a new file is opened.

Use is_opened() const to test if the file successfully opened.

Parameters

pFileName	Pointer to a Filename object
uAccess	Enumeration on permissions requested on the opened file

See also: File(const char*, eFileAccess), open(Filename*, eFileAccess), close()

◆ ~File()

Burger::File::~File ( )

Close any open file.

Shut down the File object and close the open file if it was still open.

See also: close()

Member Function Documentation

◆ close()

Burger::eError BURGER_API Burger::File::close ( void )

noexcept

Close open file.

Close previously opened file. If there was no open file, this function performs no operation and returns kErrorNone

Returns: kErrorNone if no error, error code if not.

See also: open(const char*, eFileAccess) and open(Filename*, eFileAccess)

◆ close_async()

Burger::eError BURGER_API Burger::File::close_async ( void )

noexcept

Close open file asynchronously.

Queue up a close file event, if needed.

Returns: kErrorNone if no error, error code if not.

See also: open(const char*, eFileAccess) and open(Filename*, eFileAccess)

◆ get_creation_time()

Burger::eError BURGER_API Burger::File::get_creation_time ( TimeDate_t * pOutput )

noexcept

Get the time the file was created.

If a file is open, query the operating system for the time the file was created.

Parameters

pOutput Pointer to a TimeDate_t to receive the file creation time

Returns: kErrorNone if successful, kErrorNotSupportedOnThisPlatform if not available or other codes for errors

See also: get_modification_time() or set_creation_time()

◆ get_creator_type()

uint32_t BURGER_API Burger::File::get_creator_type ( void )

noexcept

Get the file's auxiliary type.

If a file is open, call the MacOS operating system to get the file's auxiliary type.

The file's auxiliary type is usually set to the application ID code.

Note: This is a MacOS exclusive feature. If the application is not running on MacOS, it will fail by returning zero.

Returns: The four byte code or zero on failure

See also: set_creator_type() or get_file_type()

◆ get_file_pointer()

Burger::File::get_file_pointer ( void ) const

inlinenoexcept

Return the native file reference.

If a file was opened, the underlying operating system will create a file reference and it is stored within the File object.

Note: This value is platform specific. This is only to be used by platform specific code for use with operating system calls beyond the scope of the Burgerlib API.

Returns: Native file system file reference or nullptr if invalid.

See also: get_filename() or set_file_pointer(void *)

◆ get_file_size()

uint64_t BURGER_API Burger::File::get_file_size ( void )

noexcept

Return the size of a file in bytes.

If a file is open, query the operating system for the size of the file in bytes.

Note: The return value is 64 bits wide, which may be larger than the amount of available memory on some systems.

Returns: 0 if error or an empty file. Non-zero is the size of the file in bytes.

See also: read(void*, uintptr_t) and write(const void*, uintptr_t)

◆ get_file_type()

uint32_t BURGER_API Burger::File::get_file_type ( void )

noexcept

Get the file's type code.

If a file is open, call the MacOS operating system to get the file's type code.

Note: This is a MacOS exclusive feature. If the application is not running on MacOS, it will fail by returning zero.

Returns: The four byte code or zero on failure

See also: set_file_type() or get_creator_type()

◆ get_filename()

Burger::File::get_filename ( void )

inlinenoexcept

Return Filename object.

If a file was opened, the filename is cached in the File object. This call will return a pointer to that cached filename.

Note: Do not assign a new filename to the object. It's only for information purposes and not for modification.

Returns: Pointer to the contained Filename object.

See also: is_opened(void) const or get_file_pointer(void) const

◆ get_mark()

uint64_t BURGER_API Burger::File::get_mark ( void )

noexcept

Get the current file mark.

If a file is open, query the operating system for the location of the file mark for future reads or writes.

Returns: Current file mark or zero if an error occurred

See also: write(const void*, uintptr_t) or set_mark(uint64_t)

◆ get_modification_time()

Burger::eError BURGER_API Burger::File::get_modification_time ( TimeDate_t * pOutput )

noexcept

Get the time the file was last modified.

If a file is open, query the operating system for the last time the file was modified.

Parameters

pOutput Pointer to a TimeDate_t to receive the file modification time

Returns: kErrorNone if successful, kErrorNotSupportedOnThisPlatform if not available or other codes for errors

See also: get_creation_time() or set_modification_time()

◆ is_opened()

Burger::File::is_opened ( void ) const

inlinenoexcept

Return TRUE if a file is open.

Test if a file is currently open. If there's an active file, return TRUE, otherwise return FALSE

Returns: TRUE if there's an open file

See also: open(const char*, eFileAccess) and open(Filename*, eFileAccess)

◆ New() [1/2]

Burger::File *BURGER_API Burger::File::New	(	const char *	pFileName,
		eFileAccess	uAccess = kReadOnly )

staticnoexcept

Create a new File instance.

Allocate memory using Burger::Alloc() and initialize a File with it.

Parameters

pFileName	Pointer to a "C" string containing a Burgerlib pathname
uAccess	Enumeration on permissions requested on the opened file

Returns: nullptr if out of memory or the file didn't successfully open

See also: Delete(const T*)

◆ New() [2/2]

Burger::File *BURGER_API Burger::File::New	(	Filename *	pFileName,
		eFileAccess	uAccess = kReadOnly )

staticnoexcept

Create a new File instance.

Allocate memory using Burger::Alloc() and initialize a File with it.

Parameters

pFileName	Pointer to a Burger::Filename object
uAccess	Enumeration on permissions requested on the opened file

Returns: nullptr if out of memory or the file didn't successfully open

See also: Delete(const T*)

◆ open() [1/2]

Burger::eError BURGER_API Burger::File::open	(	const char *	pFileName,
		eFileAccess	uAccess = kReadOnly )

noexcept

Open a file using a Burgerlib pathname.

Close any previously opened file and open a new file.

Parameters

pFileName	Pointer to a "C" string containing a Burgerlib pathname
uAccess	Enumeration on permissions requested on the opened file

Returns: kErrorNone if no error, error code if not.

See also: open(Filename*, eFileAccess) and File(const char*, eFileAccess)

◆ open() [2/2]

Burger::eError BURGER_API Burger::File::open	(	Filename *	pFileName,
		eFileAccess	uAccess = kReadOnly )

noexcept

Open a file using a Filename.

Close any previously opened file and open a new file.

Parameters

pFileName	Pointer to a Filename object
uAccess	Enumeration on permissions requested on the opened file

Returns: kErrorNone if no error, error code if not.

See also: open(const char*, eFileAccess) and File(const char*, eFileAccess)

◆ open_async() [1/2]

Burger::eError BURGER_API Burger::File::open_async	(	const char *	pFileName,
		eFileAccess	uAccess = kReadOnly )

noexcept

Open a file asynchronously.

Create an event in the FileManager queue to open this file.

Parameters

pFileName	Pointer to a "C" string containing a Burgerlib pathname
uAccess	Enumeration on permissions requested on the opened file

Returns: kErrorNone if successful, kErrorNotSupportedOnThisPlatform if not available or other codes for errors.

See also: close_async()

◆ open_async() [2/2]

Burger::eError BURGER_API Burger::File::open_async	(	Filename *	pFileName,
		eFileAccess	uAccess = kReadOnly )

noexcept

Open a file asynchronously.

Create an event in the FileManager queue to open this file.

Parameters

pFileName	Pointer to a Filename object
uAccess	Enumeration on permissions requested on the opened file

Returns: kErrorNone if successful, kErrorNotSupportedOnThisPlatform if not available or other codes for errors.

See also: close_async()

◆ operator=() [1/2]

File & Burger::File::operator= ( const File & )

privatedelete

◆ operator=() [2/2]

File & Burger::File::operator= ( File && )

privatedelete

◆ read()

uintptr_t BURGER_API Burger::File::read	(	void *	pOutput,
		uintptr_t	uSize )

noexcept

Read data from an open file.

If a file is open, perform a read operation. This function will fail if the file was not opened for read access.

Parameters

pOutput	Pointer to a buffer of data to read from a file
uSize	Number of bytes to read

Returns: Number of bytes read (Can be less than what was requested due to EOF or read errors)

See also: write(const void*, uintptr_t)

◆ read_async()

Burger::eError BURGER_API Burger::File::read_async	(	void *	pOutput,
		uintptr_t	uSize )

noexcept

Read open file asynchronously.

Queue up a read file event.

Parameters

pOutput	Pointer to buffer to receive the data.
uSize	Size in byte of the read operation.

Returns: kErrorNone if no error, error code if not.

See also: open(const char*, eFileAccess) and open(Filename*, eFileAccess)

◆ read_big_uint16()

uint16_t BURGER_API Burger::File::read_big_uint16 ( void )

noexcept

Read a big endian 16-bit value from a file.

Given a file opened for reading, read a 16-bit value in big endian format from the file stream.

Returns: A 16 bit big endian short converted to native endian

See also: read_big_uint32() and read_little_uint16()

◆ read_big_uint32()

uint32_t BURGER_API Burger::File::read_big_uint32 ( void )

noexcept

Read a big endian 32-bit value from a file.

Given a file opened for reading, read a 32-bit value in big endian format from the file stream.

Returns: A 32 bit big endian int converted to native endian

See also: read_big_uint16() and read_little_uint32()

◆ read_c_string()

Burger::eError BURGER_API Burger::File::read_c_string	(	char *	pOutput,
		uintptr_t	uLength )

noexcept

Read a "C" string with the terminating zero to a file stream.

Read a "C" string with a terminating zero from the file stream. If the string read is larger than the buffer, it is truncated. The buffer will have an ending zero on valid read or a trucated read. If uLength was zero, then pInput can be nullptr

Parameters

pOutput	Pointer to a "C" string to write.
uLength	Size of the buffer (To prevent overruns)

Returns: Zero if the string was read, kErrorEndOfFile hit EOF

See also: WriteCString(FILE *, const char *)

◆ read_little_uint16()

uint16_t BURGER_API Burger::File::read_little_uint16 ( void )

noexcept

Read a little endian 16-bit value from a file.

Given a file opened for reading, read a 16-bit value in little endian format from the file stream.

Returns: A 16 bit little endian short converted to native endian

See also: read_little_uint32() and read_big_uint16()

◆ read_little_uint32()

uint32_t BURGER_API Burger::File::read_little_uint32 ( void )

noexcept

Read a little endian 32-bit value from a file.

Given a file opened for reading, read a 32-bit value in little endian format from the file stream.

Returns: A 32 bit little endian int converted to native endian

See also: read_little_uint16() and read_big_uint32()

◆ set_creation_time()

Burger::eError BURGER_API Burger::File::set_creation_time ( const TimeDate_t * pInput )

noexcept

Set the time the file was created.

If a file is open, call the operating system to set the file creation time to the passed value.

Parameters

pInput Pointer to a TimeDate_t to use for the new file creation time

Returns: kErrorNone if successful, kErrorNotSupportedOnThisPlatform if not available or other codes for errors

See also: get_creation_time() or set_modification_time()

◆ set_creator_and_file_type()

Burger::eError BURGER_API Burger::File::set_creator_and_file_type	(	uint32_t	uCreatorType,
		uint32_t	uFileType )

noexcept

Set the file's auxiliary and file type.

If a file is open, call the MacOS operating system to set the file's auxiliary and file types to the passed values.

The file's auxiliary type is usually set to the application ID code.

Note: This is a MacOS exclusive feature. If the application is not running on MacOS, it will fail with a code of kErrorNotSupportedOnThisPlatform.

Parameters

uCreatorType	Value to set the file's auxiliary type
uFileType	Value to set the file's type

Returns: kErrorNone if successful, kErrorNotSupportedOnThisPlatform if not available or other codes for errors

See also: set_file_type() or set_creator_type()

◆ set_creator_type()

Burger::eError BURGER_API Burger::File::set_creator_type ( uint32_t uCreatorType )

noexcept

Set the file's auxiliary type.

If a file is open, call the MacOS operating system to set the file's auxiliary type to the passed value.

The file's auxiliary type is usually set to the application ID code.

Note: This is a MacOS and Darwin exclusive feature. If the application is not running on Apple operating system, it will fail with a code of kErrorNotSupportedOnThisPlatform.

Parameters

uCreatorType Value to set the file's creator type

Returns: kErrorNone if successful, kErrorNotSupportedOnThisPlatform if not available or other codes for errors

See also: set_creator_and_file_type(), set_file_type() or get_creator_type()

◆ set_file_pointer()

Burger::File::set_file_pointer ( void * pFile )

inlinenoexcept

Set the native file reference.

If using platform specific code to open a file using special privileges beyond the Burgerlib API, this call will allow code to manually set the file reference.

Note: This call is platform specific and great care is required for its use.

Parameters

pFile Native file reference.

See also: get_file_pointer() const or close()

◆ set_file_type()

Burger::eError BURGER_API Burger::File::set_file_type ( uint32_t uFileType )

noexcept

Set the file's type code.

If a file is open, call the MacOS operating system to set the file's type to the passed value.

Note: This is a MacOS and Darwin exclusive feature. If the application is not running on Apple operating system, it will fail with a code of kErrorNotSupportedOnThisPlatform.

Parameters

uFileType Value to set the file's type

Returns: kErrorNone if successful, kErrorNotSupportedOnThisPlatform if not available or other codes for errors

See also: set_creator_and_file_type(), set_creator_type() or get_file_type()

◆ set_mark()

Burger::eError BURGER_API Burger::File::set_mark ( uint64_t uMark )

noexcept

Set the current file mark.

If a file is open, set the read/write mark at the location passed.

Parameters

uMark Value to set the new file mark to.

Returns: kErrorNone if successful, kErrorOutOfBounds if not.

See also: get_mark() or set_mark_at_EOF()

◆ set_mark_at_EOF()

Burger::eError BURGER_API Burger::File::set_mark_at_EOF ( void )

noexcept

Set the current file mark at the end of the file.

If a file is open, set the read/write mark to the end of the file.

Returns: kErrorNone if successful, kErrorOutOfBounds if not.

See also: get_mark() or set_mark(uint64_t)

◆ set_modification_time()

Burger::eError BURGER_API Burger::File::set_modification_time ( const TimeDate_t * pInput )

noexcept

Set the time the file was last modified.

If a file is open, call the operating system to set the file modification time to the passed value.

Parameters

pInput Pointer to a TimeDate_t to use for the new file modification time

Returns: kErrorNone if successful, kErrorNotSupportedOnThisPlatform if not available or other codes for errors

See also: get_modification_time() or set_creation_time()

◆ write()

uintptr_t BURGER_API Burger::File::write	(	const void *	pInput,
		uintptr_t	uSize )

noexcept

Write data into an open file.

If a file is open, perform a write operation. This function will fail if the file was not opened for write access.

Parameters

pInput	Pointer to a buffer of data to write to a file
uSize	Number of bytes to write

Returns: Number of bytes written (Can be less than what was requested due to EOF or write errors)

See also: read(void *, uintptr_t)

Member Data Documentation

◆ m_bUsingFSRef

uint_t Burger::File::m_bUsingFSRef

protected

True if using MacOS 9 or higher APIs (MacOS Only)

◆ m_Filename

Filename Burger::File::m_Filename

protected

Name of the file that was opened.

◆ m_pFile

void* Burger::File::m_pFile

protected

Open file reference.

Public Types

Public Member Functions

Static Public Member Functions

Protected Attributes

Private Member Functions

Detailed Description

Member Enumeration Documentation

◆ eFileAccess

Constructor & Destructor Documentation

◆ File() [1/5]

◆ File() [2/5]

◆ File() [3/5]

◆ File() [4/5]

◆ File() [5/5]

◆ ~File()

Member Function Documentation

◆ close()

◆ close_async()

◆ get_creation_time()

◆ get_creator_type()

◆ get_file_pointer()

◆ get_file_size()

◆ get_file_type()

◆ get_filename()

◆ get_mark()

◆ get_modification_time()

◆ is_opened()

◆ New() [1/2]

◆ New() [2/2]

◆ open() [1/2]

◆ open() [2/2]

◆ open_async() [1/2]

◆ open_async() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ read()

◆ read_async()

◆ read_big_uint16()

◆ read_big_uint32()

◆ read_c_string()

◆ read_little_uint16()

◆ read_little_uint32()

◆ set_creation_time()

◆ set_creator_and_file_type()

◆ set_creator_type()

◆ set_file_pointer()

◆ set_file_type()

◆ set_mark()

◆ set_mark_at_EOF()

◆ set_modification_time()

◆ write()

Member Data Documentation

◆ m_bUsingFSRef

◆ m_Filename

◆ m_pFile