Global file system manager. More...

#include <fmfile.h>

Collaboration diagram for Burger::FileManager:

Classes
struct	ExpandCache_t
	Structure to contain a directory cache entry. More...
Static Public Member Functions
static void BURGER_API	Init (void)
	Initialize the global file system manager.
static void BURGER_API	Shutdown (void)
	Shut down the global file system manager.
static Word BURGER_API	GetVolumeName (Burger::Filename *pOutput, Word uVolumeNum)
	Return the name of a drive.
static Word BURGER_API	GetVolumeNumber (const char *pInput)
	Given a volume name, return the volume number it's mounted on.
static void BURGER_API	DefaultPrefixes (void)
	Set the initial default prefixs for a power up state.
static Word BURGER_API	GetPrefix (Filename *pOutput, Word uPrefixNum)
	Return the contents of a prefix.
static Word BURGER_API	SetPrefix (Word uPrefixNum, const char *pPrefixName)
	Set the contents of a prefix.
static void BURGER_API	PopPrefix (Word uPrefixNum)
	Remove the last entry of a prefix.
static Word BURGER_API	GetModificationTime (const char pFileName, Burger::TimeDate_t pOutput)
	Get a file's last modification time.
static Word BURGER_API	GetModificationTimeNative (const Burger::Filename pFileName, Burger::TimeDate_t pOutput)
	Get a file's last modification time.
static Word BURGER_API	GetCreationTime (const char pFileName, Burger::TimeDate_t pOutput)
	Get a file's creation time.
static Word BURGER_API	GetCreationTimeNative (const Burger::Filename pFileName, Burger::TimeDate_t pOutput)
	Get a file's creation time.
static Word BURGER_API	DoesFileExist (const char *pFileName)
	Detect for a file's existance.
static Word BURGER_API	DoesFileExistNative (const Burger::Filename *pFileName)
	Detect for a file's existance using a native pathname.
static Word32 BURGER_API	GetAuxType (const char *pFileName)
	Return a file's creator code.
static Word32 BURGER_API	GetAuxTypeNative (const Burger::Filename *pFileName)
	Return a file's type code using a native filename.
static Word32 BURGER_API	GetFileType (const char *pFileName)
	Return a file's type code.
static Word32 BURGER_API	GetFileTypeNative (const Burger::Filename *pFileName)
	Return a file's creator code using a native filename.
static Word BURGER_API	GetFileAndAuxType (const char pFileName, Word32 pFileType, Word32 *pAuxType)
	Return a file's type and creator codes.
static Word BURGER_API	GetFileAndAuxTypeNative (const Burger::Filename pFileName, Word32 pFileType, Word32 *pAuxType)
	Return a file's type and creator codes using a native filename.
static Word BURGER_API	SetAuxType (const char *pFileName, Word32 uAuxType)
	Set a file's creator code.
static Word BURGER_API	SetAuxTypeNative (const Burger::Filename *pFileName, Word32 uAuxType)
	Set a file's type code using a native filename.
static Word BURGER_API	SetFileType (const char *pFileName, Word32 uFileType)
	Set a file's type code.
static Word BURGER_API	SetFileTypeNative (const Burger::Filename *pFileName, Word32 uFileType)
	Set a file's type code using a native filename.
static Word BURGER_API	SetFileAndAuxType (const char *pFileName, Word32 uFileType, Word32 uAuxType)
	Set a file's type and creator codes.
static Word BURGER_API	SetFileAndAuxTypeNative (const Burger::Filename *pFileName, Word32 uFileType, Word32 uAuxType)
	Set a file's type and creator codes using a native filename.
static Word BURGER_API	CreateDirectoryPath (const char *pFileName)
	Create a directory path.
static Word BURGER_API	CreateDirectoryPathMinusFile (const char *pFileName)
	Create a directory path sans the last filename token.
static Word BURGER_API	CreateDirectoryPathNative (const Burger::Filename *pFileName)
	Create a directory path using an OS native pathname.
static Word BURGER_API	DeleteFile (const char *pFileName)
	Delete a file.
static Word BURGER_API	DeleteFileNative (const Burger::Filename *pFileName)
	Delete a file using an OS pathname.
static Word BURGER_API	RenameFile (const char pNewName, const char pOldName)
	Rename a file.
static Word BURGER_API	RenameFileNative (const Burger::Filename pNewName, const Burger::Filename pOldName)
	Rename a file using OS native pathnames.
static Word BURGER_API	ChangeOSDirectory (const char *pDirName)
	Change the OS working directory.
static Word BURGER_API	ChangeOSDirectoryNative (const Burger::Filename *pDirName)
	Change the OS working directory using an OS native pathname..
static FILE *BURGER_API	OpenFile (const char pFileName, const char pType)
	Open a file using stdio.
static Word BURGER_API	CopyFile (const char pDestName, const char pSrcName)
	Copy a file.
static Word BURGER_API	CopyFileNative (const Burger::Filename pDestName, const Burger::Filename pSrcName)
	Copy a file using OS native pathnames.
static Word BURGER_API	SaveFile (const char pFileName, const void pData, WordPtr uLength)
	Save a file.
static Word BURGER_API	SaveFileNative (const Burger::Filename pFileName, const void pData, WordPtr uLength)
	Save a file using an OS native pathname.
static Word BURGER_API	SaveTextFile (const char pFileName, const void pData, WordPtr uLength)
	Save a text file.
static Word BURGER_API	SaveTextFileNative (const Burger::Filename pFileName, const void pData, WordPtr uLength)
	Save a text file using an OS native filename.
static void *BURGER_API	LoadFile (const char pFileName, WordPtr pLength)
	Load a file into memory.
static void *BURGER_API	LoadFileNative (const Burger::Filename pFileName, WordPtr pLength)
	Load a file into memory using a native OS pathname.
static Word BURGER_API	AreLongFilenamesAllowed (void)
	Returns TRUE if long filenames are allowed.
Static Public Attributes
static const Word	PREFIXCURRENT = 8
	8: Current working directory at application launch
static const Word	PREFIXAPPLICATION = 9
	9: Directory where the application executable resides
static const Word	PREFIXBOOT = 32
	"*:" Boot volume prefix number
static const Word	PREFIXPREFS = 33
	"@:" User preferences folder prefix number
static const Word	PREFIXSYSTEM = 34
	"$:" System volume folder prefix number
static const Word	PREFIXMAX = 35
	Maximum number of pathname prefixes.
Private Member Functions
void	ReleasePrefixes (void)
	Reset all file prefixes.
Static Private Member Functions
static void	InitDirectoryCache (void)
	Initialize the directory cache.
static void	PurgeDirectoryCache (void)
	Dispose of my directory cache.
Private Attributes
const char *	m_pPrefix [Burger::FileManager::PREFIXMAX]
	Array of prefix strings.
Word8	m_bAllowed
	True if MSDOS has long filename support (MSDOS Only).
Word	m_uBootNameSize
	Length of the boot volume name (MACOSX Only).
char	m_BootName [256]
	Boot volume name in the format ":FooBar" (Not zero terminated) (MACOSX Only).
ExpandCache_t	m_DirectoryCache [DIRCACHESIZE]
	Directory cache (MAC Classic/Carbon Only).
Static Private Attributes
static const Word	DIRCACHESIZE = 8
	Number of cache entries.
static FileManager	g_FileManager
	Global instance of the file manager.
Friends
class	Filename

Detailed Description

Global file system manager.

Since file systems are all tied to a single device such as a hard drive or DVD Rom, all file calls are routed through a singleton class to enable Burgerlib to prioritize file streaming to reduce seeks and read/write operations for peak performance.

To ensure cross platform compatibility, all file/pathnames use a generic universal format that BurgerLib will accept and the library will perform any translations needed to the exact same behavior is consistant across operating systems.

The strings are "C" format, 8 bit ascii with a zero termination byte. They are encoded using strict UTF8 format. Colons are used at filename delimiters.

The concept of a BurgerLib path is simple. The first part is either a drive specifier, a volume name or a directory prefix. Drive specifiers act much like "C:" does on Windows machines. Volume names allow you to ask for a CD or DVD by name and query if it is mounted irregardless of which drive it physically resides. Prefixes act like current working directories except that there are over 30 of them active at the same time and with a numeric or special character code you can quickly select the desired one at runtime.

Some prefixes are preset after a call to Burger::FileManager::DefaultPrefixes().

Default prefixes:
"8:" = Current working directory at application launch
"9:" = Directory where the application resides
"*:" = Boot drive volume
"@:" = Directory for the user's data. OS specific as to the location (Usually the Users' folder)
"$:" = System folder (System on MacOS or Windows on Windows)
"14:" = User prefix #14, the number can be 0 through 31.

Example pathnames:
"9:GameData.dat" = Data file sitting next to the application
"@:Contraband Entertainment:CoolGame:MyPrefs.bin" = Preferences file
"*:Root.txt" = File at the root of the boot drive
"20:LevelData.bin" = Application defined prefix and file within the expected directory structure

See also:: Burger::UTF8

Member Function Documentation

Word BURGER_API Burger::FileManager::AreLongFilenamesAllowed ( void ) [static]

Returns TRUE if long filenames are allowed.

On some MSDOS file systems, only 8.3 filenames are permitted. Test if support for longer than 8.3 filenames is present and if so, return TRUE, otherwise return FALSE.

Note:: This function returns TRUE on all target platforms except BURGER_MSDOS, the MS/DOS target performs a check to see if it's running under Windows 95 or higher and if so, Burgerlib will automatically support long filenames.

See also:: Burger::FileManager

Word BURGER_API Burger::FileManager::ChangeOSDirectory ( const char * pDirName ) [static]

Change the OS working directory.

Given a BurgerLib pathname, set the OS's current working directory to this path.

This function is useful in cases where an OS native file dialog to select a file or perform an OS native function where the current working directory needs to be preset. This function under most circumstances is not necessary to use, however, it exists since there are some OS native functions in MacOS and Windows that require a little "help".

Parameters:

pDirName

Pointer to a "C" string of a BurgerLib path.

Returns:: Zero if successful, non-zero on error.

See also:: Burger::FileManager::ChangeOSDirectoryNative(const Burger::Filename *)

Word BURGER_API Burger::FileManager::ChangeOSDirectoryNative ( const Burger::Filename * pDirName ) [static]

Change the OS working directory using an OS native pathname..

Given an OS native pathname, set the OS's current working directory to this path.

This function is useful in cases where an OS native file dialog to select a file or perform an OS native function where the current working directory needs to be preset. This function under most circumstances is not necessary to use, however, it exists since there are some OS native functions in MacOS and Windows that require a little "help".

Parameters:

pDirName

Pointer to a Burger::Filename of a native OS path.

Returns:: Zero if successful, non-zero on error.

See also:: Burger::FileManager::ChangeOSDirectory(const char *)

Word BURGER_API Burger::FileManager::CopyFile	(	const char *	pDestName,
		const char *	pSrcName
	)			`[static]`

Copy a file.

Given a BurgerLib formatted old pathname and new pathname, make a duplicate of the file at the end of the pathname.

Parameters:

	pDestName	Pointer to a "C" string of a BurgerLib path for the new name.
	pSrcName	Pointer to a "C" string of a BurgerLib path for the current file name.

Returns:: Zero if successful, non-zero on error.

See also:: Burger::FileManager::CopyFileNative(const Burger::Filename *,const Burger::Filename *)

Word BURGER_API Burger::FileManager::CopyFileNative	(	const Burger::Filename *	pDestName,
		const Burger::Filename *	pSourceName
	)			`[static]`

Copy a file using OS native pathnames.

Given an OS native formatted old pathname and new pathname, make a duplicate of the file at the end of the pathname.

Parameters:

	pDestName	Pointer to a Burger::Filename of an OS native path for the new name.
	pSourceName	Pointer to a Burger::Filename of an OS native path for the current file name.

Returns:: Zero if successful, non-zero on error.

See also:: Burger::FileManager::CopyFile(const char *,const char *)

Word BURGER_API Burger::FileManager::CreateDirectoryPath ( const char * pFileName ) [static]

Create a directory path.

Given a BurgerLib directory, create each and every part of the directory. If the directory already exists, or is successfully created, the call is considered successful.

Example:
If the path :Foo:Bar: exists, a call with ":Foo:Bar:Fooey:Temp:" will create both "Fooey" and "Temp" in this single call.

Parameters:

pFileName

Pointer to a "C" string of a BurgerLib path.

Returns:: Zero if successful, non-zero on error.

See also:: Burger::FileManager::CreateDirectoryPathMinusFile(const char *)

Word BURGER_API Burger::FileManager::CreateDirectoryPathMinusFile ( const char * pFileName ) [static]

Create a directory path sans the last filename token.

Given a BurgerLib directory, create each and every part of the directory from a path that includes a filename. If the directory already exists, or is successfully created, the call is considered successful.

Example:
If the path :Foo:Bar: exists, a call with ":Foo:Bar:Fooey:Temp:File.txt" will create both "Fooey" and "Temp" in this single call. The last token of "File.txt" is ignored.

Parameters:

pFileName

Pointer to a "C" string of a BurgerLib path.

Returns:: Zero if successful, non-zero on error.

See also:: Burger::FileManager::CreateDirectoryPath(const char *)

Word BURGER_API Burger::FileManager::CreateDirectoryPathNative ( const Burger::Filename * pFileName ) [static]

Create a directory path using an OS native pathname.

Given an OS native directory, create each and every part of the directory. If the directory already exists, or is successfully created, the call is considered successful.

Example:
If the path c:\Foo\Bar exists, a call with "c:\Foo\Bar\Fooey\Temp\" will create both "Fooey" and "Temp" in this single call.

Parameters:

pFileName

Pointer to a Burger::Filename that contains a native OS pathname.

Returns:: Zero if successful, non-zero on error.

See also:: Burger::FileManager::CreateDirectoryPath(const char *) or Burger::FileManager::CreateDirectoryPathMinusFile(const char *)

void BURGER_API Burger::FileManager::DefaultPrefixes ( void ) [static]

Set the initial default prefixs for a power up state.

Sets these prefixes based on the current setup of the machine the application is running on.

"*:" = Boot volume
"$:" = System folder
"@:" = Prefs folder
"8:" = Default directory
"9:" = Application directory

See also:: Burger::FileManager::Init(void), Burger::FileManager::GetPrefix(Burger::Filename *,Word) or Burger::FileManager::SetPrefix(Word,const char *)

Word BURGER_API Burger::FileManager::DeleteFile ( const char * pFileName ) [static]

Delete a file.

Given a BurgerLib pathname, delete the file at the end of the pathname.

Example:
If a call with ":Foo:Bar:Fooey:Temp.txt" is issued, only the file "Temp.txt" is deleted. The rest of the path is left intact. This call will not delete directories, only files. If the file is already deleted, an error is returned.

Parameters:

pFileName

Pointer to a "C" string of a BurgerLib path.

Returns:: Zero if successful, non-zero on error.

See also:: Burger::FileManager::DeleteFileNative(const Burger::Filename *)

Word BURGER_API Burger::FileManager::DeleteFileNative ( const Burger::Filename * pFileName ) [static]

Delete a file using an OS pathname.

Given an OS native pathname, delete the file at the end of the pathname.

Example:
If a call with "c:\Foo\Bar\Fooey\Temp.txt" is issued, only the file "Temp.txt" is deleted. The rest of the path is left intact. This call will not delete directories, only files. If the file is already deleted, an error is returned.

Parameters:

pFileName

Pointer to a Burger::Filename of a native OS path.

Returns:: Zero if successful, non-zero on error.

See also:: Burger::FileManager::DeleteFile(const char *)

Word BURGER_API Burger::FileManager::DoesFileExist ( const char * pFileName ) [static]

Detect for a file's existance.

Given a BurgerLib pathname, return TRUE if the file exists. FALSE if there is an disk error or the file does not exist.

Parameters:

pFileName

Pointer to a "C" string of a BurgerLib pathname,

Returns:: FALSE if the file does not exist, TRUE if the file exists.

Note:: This does not guarantee that the file can be opened due to security permissions or the file being on a locked folder. It only guarantees its existence.

See also:: Burger::FileManager::DoesFileExistNative(const Burger::Filename *)

Word BURGER_API Burger::FileManager::DoesFileExistNative ( const Burger::Filename * pFileName ) [static]

Detect for a file's existance using a native pathname.

Given a OS native pathname, return TRUE if the file exists. FALSE if there is an disk error or the file does not exist.

Parameters:

pFileName

Pointer to a Burger::Filename which contains a native version of the path to the file.

Returns:: FALSE if the file does not exist, TRUE if the file exists.

Note:: This does not guarantee that the file can be opened due to security permissions or the file being on a locked folder. It only guarantees its existence.

See also:: Burger::Filename::ToNative(const char *) or Burger::FileManager::DoesFileExist(const char *)

Word32 BURGER_API Burger::FileManager::GetAuxType ( const char * pFileName ) [static]

Return a file's creator code.

On MacOS, a file has extended data which includes the application code that owns the file. This function will retrieve the 4 byte code from the file.

On non MacOS platforms, this function only return 0 (An error condition) and perform nothing..

Parameters:

pFileName

Pointer to a "C" string of a BurgerLib pathname,

Returns:: 0 if the file doesn't exist, the function isn't implemented of if the file doesn't have extended information. A 32 bit value if the data can be retrieved.

See also:: Burger::FileManager::GetAuxTypeNative(const Burger::Filename *), Burger::FileManager::GetFileType(const char *) or Burger::FileManager::GetFileAndAuxType(const char *,Word32 *,Word32 *)

Word32 BURGER_API Burger::FileManager::GetAuxTypeNative ( const Burger::Filename * pFileName ) [static]

Return a file's type code using a native filename.

On MacOS, a file has extended data which includes the file's type, which is independent of the filename. This function will retrieve the 4 byte code from the file.

On non MacOS platforms, this function only return 0 (An error condition) and perform nothing..

Parameters:

pFileName

Pointer to a Burger::Filename of a native OS pathname,

Returns:: 0 if the file doesn't exist, the function isn't implemented of if the file doesn't have extended information. A 32 bit value if the data can be retrieved.

See also:: Burger::FileManager::GetFileType(const char *), Burger::FileManager::GetAuxType(const char *) or Burger::FileManager::GetFileAndAuxType(const char *,Word32 *,Word32 *)

Word BURGER_API Burger::FileManager::GetCreationTime	(	const char *	pFileName,
		Burger::TimeDate_t *	pOutput
	)			`[static]`

Get a file's creation time.

Given a BurgerLib path, access the file and return the time/date that it was created.

Parameters:

	pFileName	Pointer to a "C" string to a BurgerLib pathname
	pOutput	Pointer to an uninitialized Burger::TimeDate_t structure that will receive the time/date.

Returns:: Zero on success, non-zero in the event of an error (Usually file not found)

See also:: Burger::FileManager::GetCreationTimeNative(const Burger::Filename *,Burger::TimeDate_t *)

Word BURGER_API Burger::FileManager::GetCreationTimeNative	(	const Burger::Filename *	pFileName,
		Burger::TimeDate_t *	pOutput
	)			`[static]`

Get a file's creation time.

Given a native operating system path, access the file and return the time/date that it was created.

Parameters:

	pFileName	Pointer to a Burger::Filename class that is properly initialized to the native file system.
	pOutput	Pointer to an uninitialized Burger::TimeDate_t structure that will receive the time/date.

Returns:: Zero on success, non-zero in the event of an error (Usually file not found)

See also:: Burger::Filename::ToNative(const char *) or Burger::FileManager::GetCreationTime(const char *,Burger::TimeDate_t *)

Word BURGER_API Burger::FileManager::GetFileAndAuxType	(	const char *	pFileName,
		Word32 *	pFileType,
		Word32 *	pAuxType
	)			`[static]`

Return a file's type and creator codes.

On MacOS, a file has extended data which includes the file's type, which is independent of the filename, and the creator code of the application that owns this file. This function will retrieve the 4 byte codes from the file.

On non MacOS platforms, this function only return non-zero (An error condition) and perform store zeros in the result values..

Parameters:

	pFileName	Pointer to a "C" string of a BurgerLib pathname,
	pFileType	Pointer to a Word32 that will receive the file type code.
	pAuxType	Pointer to a Word32 that will receive the file creator code.

Returns:: Non-zero if the file doesn't exist, the function isn't implemented of if the file doesn't have extended information. Zero is returned on successfull completion.

See also:: Burger::FileManager::GetFileAndAuxTypeNative(const Burger::Filename *,Word32 *,Word32 *), Burger::FileManager::GetFileType(const char *) or Burger::FileManager::GetAuxType(const char *)

Word BURGER_API Burger::FileManager::GetFileAndAuxTypeNative	(	const Burger::Filename *	pFileName,
		Word32 *	pFileType,
		Word32 *	pAuxType
	)			`[static]`

Return a file's type and creator codes using a native filename.

On MacOS, a file has extended data which includes the file's type, which is independent of the filename, and the creator code of the application that owns this file. This function will retrieve the 4 byte codes from the file.

On non MacOS platforms, this function only return non-zero (An error condition) and perform store zeros in the result values..

Parameters:

	pFileName	Pointer to a Burger::Filename of a native OS pathname,
	pFileType	Pointer to a Word32 that will receive the file type code.
	pAuxType	Pointer to a Word32 that will receive the file creator code.

Returns:: Non-zero if the file doesn't exist, the function isn't implemented of if the file doesn't have extended information. Zero is returned on successfull completion.

See also:: Burger::FileManager::GetFileAndAuxTypeNative(const Burger::Filename *,Word32 *,Word32 *), Burger::FileManager::GetFileType(const char *) or Burger::FileManager::GetAuxType(const char *)

Word32 BURGER_API Burger::FileManager::GetFileType ( const char * pFileName ) [static]

Return a file's type code.

On MacOS, a file has extended data which includes the file's type, which is independent of the filename. This function will retrieve the 4 byte code from the file.

On non MacOS platforms, this function only return 0 (An error condition) and perform nothing..

Parameters:

pFileName

Pointer to a "C" string of a BurgerLib pathname,

Returns:: 0 if the file doesn't exist, the function isn't implemented of if the file doesn't have extended information. A 32 bit value if the data can be retrieved.

See also:: Burger::FileManager::GetFileTypeNative(const Burger::Filename *), Burger::FileManager::GetAuxType(const char *) or Burger::FileManager::GetFileAndAuxType(const char *,Word32 *,Word32 *)

Word32 BURGER_API Burger::FileManager::GetFileTypeNative ( const Burger::Filename * pFileName ) [static]

Return a file's creator code using a native filename.

On MacOS, a file has extended data which includes the application code that owns the file. This function will retrieve the 4 byte code from the file.

On non MacOS platforms, this function only return 0 (An error condition) and perform nothing..

Parameters:

pFileName

Pointer to a Burger::Filename of a native OS pathname,

Returns:: 0 if the file doesn't exist, the function isn't implemented of if the file doesn't have extended information. A 32 bit value if the data can be retrieved.

See also:: Burger::FileManager::GetAuxType(const char *), Burger::FileManager::GetFileType(const char *) or Burger::FileManager::GetFileAndAuxType(const char *,Word32 *,Word32 *)

Word BURGER_API Burger::FileManager::GetModificationTime	(	const char *	pFileName,
		Burger::TimeDate_t *	pOutput
	)			`[static]`

Get a file's last modification time.

Given a BurgerLib path, access the file and return the time/date that it was last modified.

Parameters:

	pFileName	Pointer to a "C" string to a BurgerLib pathname
	pOutput	Pointer to an uninitialized Burger::TimeDate_t structure that will receive the time/date.

Returns:: Zero on success, non-zero in the event of an error (Usually file not found)

See also:: Burger::FileManager::GetModificationTimeNative(const Burger::Filename *,Burger::TimeDate_t *)

Word BURGER_API Burger::FileManager::GetModificationTimeNative	(	const Burger::Filename *	pFileName,
		Burger::TimeDate_t *	pOutput
	)			`[static]`

Get a file's last modification time.

Given a native operating system path, access the file and return the time/date that it was last modified.

Parameters:

	pFileName	Pointer to a Burger::Filename class that is properly initialized to the native file system.
	pOutput	Pointer to an uninitialized Burger::TimeDate_t structure that will receive the time/date.

Returns:: Zero on success, non-zero in the event of an error (Usually file not found)

See also:: Burger::Filename::ToNative(const char *) or Burger::FileManager::GetModificationTime(const char *,Burger::TimeDate_t *)

Word BURGER_API Burger::FileManager::GetPrefix	(	Burger::Filename *	pOutput,
		Word	uPrefixNum
	)			`[static]`

Return the contents of a prefix.

Given a prefix number, fill in a Burger::Filename structure with a copy of the prefix pathname. The string could be an empty string in the case of an unused or NULL prefix.

Parameters:

	pOutput	Pointer to a Burger::Filename class to store the string
	uPrefixNum	Index to the requested prefix to obtain

Returns:: Zero if no error, non-zero if error

See also:: Burger::FileManager::SetPrefix(Word,const char *)

Word BURGER_API Burger::FileManager::GetVolumeName	(	Burger::Filename *	pOutput,
		Word	uVolumeNum
	)			`[static]`

Return the name of a drive.

Given a drive number (0-??), return the name of the volume in the format of ":Volume name:". The function will guarantee the existance of the colons.

Note:: This function should be used with caution. Only mounted drives would return immdiately and if the drive has ejectable media may take a while for it to respond to a volume name query.

Parameters:

	pOutput	A Burger::Filename structure to contain the filename (Can be NULL)
	uVolumeNum	A valid drive number from 0-?? with ?? being the maximum number of drives in the system

Returns:: Zero if no error, non-zero if an error occured

See also:: Burger::FileManager::GetVolumeNumber(const char *)

Word BURGER_API Burger::FileManager::GetVolumeNumber ( const char * pVolumeName ) [static]

Given a volume name, return the volume number it's mounted on.

Scanning all the disk volumes, search for a drive that is labeled by the input name. The input is in the form of ":home:". The search is case insensitive.

Parameters:

pVolumeName

Valid pointer to "C" string in the form of ":name:"

Returns:: Volume number from 0-max drives and -1 in case of the volume was not found.

Note:: This function will NOT search floppy drives A: and B: on MSDOS and Windows platforms. This is to prevent an annoying error for bad media.

See also:: Burger::FileManager::GetVolumeName(Burger::Filename *,Word)

void BURGER_API Burger::FileManager::Init ( void ) [static]

Initialize the global file system manager.

Call this function once on startup to start up the burgerlib file manager. This function's primary purpose is to initialize the default prefixes.

See also:: Burger::FileManager::DefaultPrefixes(void) or Burger::FileManager::Shutdown(void)

void Burger::FileManager::InitDirectoryCache ( void ) [static, private]

Initialize the directory cache.

This function is called by Burger::FileManager::Init(void). It's not meant to be called by applications.

See also:: Burger::FileManager::PurgeDirectoryCache(void) or Burger::FileManager::ExpandCache_t

Note:: Only available on MacOS

void *BURGER_API Burger::FileManager::LoadFile	(	const char *	pFileName,
		WordPtr *	pLength
	)			`[static]`

Load a file into memory.

Given a BurgerLib pathname, open the file, allocate a buffer for it, load it into memory and return the pointer to the allocated buffer and the optional buffer size.

This function is a quick and easy way to read the contents of a file into a buffer. The buffer must be deleted with a call to Burger::GlobalMemoryManager::Free(const void *)

Note:: This function does no data translation. The buffer contains an exact byte for byte copy of the contents of the file on disk.

Parameters:

	pFileName	Pointer to a "C" string of a BurgerLib path.
	pLength	Pointer to a WordPtr to receive the size of the buffer.

Returns:: NULL if failure, a valid pointer to the buffer on success.

See also:: Burger::FileManager::LoadFileNative(const Burger::Filename *,WordPtr *)

void *BURGER_API Burger::FileManager::LoadFileNative	(	const Burger::Filename *	pFileName,
		WordPtr *	pLength
	)			`[static]`

Load a file into memory using a native OS pathname.

Given an OS native pathname, open the file, allocate a buffer for it, load it into memory and return the pointer to the allocated buffer and the optional buffer size.

This function is a quick and easy way to read the contents of a file into a buffer. The buffer must be deleted with a call to Burger::GlobalMemoryManager::Free(const void *)

Note:: This function does no data translation. The buffer contains an exact byte for byte copy of the contents of the file on disk.

Parameters:

	pFileName	Pointer to a Burger::Filename of an OS native path.
	pLength	Pointer to a WordPtr to receive the size of the buffer.

Returns:: NULL if failure, a valid pointer to the buffer on success.

See also:: Burger::FileManager::LoadFile(const char *,WordPtr *)

FILE *BURGER_API Burger::FileManager::OpenFile	(	const char *	pFileName,
		const char *	pType
	)			`[static]`

Open a file using stdio.

Given a BurgerLib pathname, open a file as if fopen() supported BurgerLib pathnames,

This is a cross platform method for opening a standard "C" library file stream. As such, this pointer must eventually be closed with a call to fclose().

The second parameter is passed as is to a subsequent call to fopen(). See the docs on fopen() on valid input such as "rb" for read binary and "w" for write text file.

Parameters:

	pFileName	Pointer to a "C" string of a BurgerLib path.
	pType	Pointer to a "C" string that will be passed to a call to fopen().

Returns:: NULL on error, a valid FILE * compatible with stdio.h file calls.

See also:: Burger::File

void BURGER_API Burger::FileManager::PopPrefix ( Word uPrefixNum ) [static]

Remove the last entry of a prefix.

Given a prefix number, pop off the last entry so that it effectively goes up one entry in a directory hiearchy. Imagine performing the operation "cd .." on the prefix.

This can force the prefix to become an empty string if the prefix is pointing to a root folder.

Examples:
":foo:bar:temp:" = ":foo:bar:"
":foo:bar:" = ":foo:"
":foo:" = ""

Parameters:

uPrefixNum

Index to the prefix to modify.

See also:: Burger::FileManager::GetPrefix(Burger::Filename *,Word) or Burger::FileManager::SetPrefix(Word,const char *)

void Burger::FileManager::PurgeDirectoryCache ( void ) [static, private]

Dispose of my directory cache.

This function is called by Burger::FileManager::Shutdown(void) or any internal function that can modify the MacOS directory structure. It's not meant to be called by applications.

See also:: Burger::FileManager::InitDirectoryCache(void) or Burger::FileManager::ExpandCache_t

Note:: Only available on MacOS

void Burger::FileManager::ReleasePrefixes ( void ) [private]

Reset all file prefixes.

Clear all file prefixes and release any memory allocated for them.

Note:: This is an internal function called on Burger::FileManager shutdown. It's not meant for application use.

See also:: Burger::FileManager::DefaultPrefixes(void)

Word BURGER_API Burger::FileManager::RenameFile	(	const char *	pNewName,
		const char *	pOldName
	)			`[static]`

Rename a file.

Given a BurgerLib formatted old pathname and new pathname, rename the file at the end of the pathname.

Note:: The source and destination directories must be the same.

Parameters:

	pNewName	Pointer to a "C" string of a BurgerLib path for the new name.
	pOldName	Pointer to a "C" string of a BurgerLib path for the current file name.

Returns:: Zero if successful, non-zero on error.

See also:: Burger::FileManager::RenameFileNative(const Burger::Filename *,const Burger::Filename *)

Word BURGER_API Burger::FileManager::RenameFileNative	(	const Burger::Filename *	pDestName,
		const Burger::Filename *	pSourceName
	)			`[static]`

Rename a file using OS native pathnames.

Given an OS native formatted old pathname and new pathname, rename the file at the end of the pathname.

Note:: The source and destination directories must be the same.

Parameters:

	pDestName	Pointer to a Burger::Filename of an OS native path for the new name.
	pSourceName	Pointer to a Burger::Filename of an OS native path for the current file name.

Returns:: Zero if successful, non-zero on error.

See also:: Burger::FileManager::RenameFile(const char *,const char *)

Word BURGER_API Burger::FileManager::SaveFile	(	const char *	pFileName,
		const void *	pInput,
		WordPtr	uLength
	)			`[static]`

Save a file.

Given a BurgerLib pathname and a buffer, save the contents of the buffer into a file and close the file.

This function is a quick and easy way to write a buffer from memory directly to disk (Or any other storage medium).

Parameters:

	pFileName	Pointer to a "C" string of a BurgerLib path.
	pInput	Pointer to an array of bytes to save
	uLength	Number of bytes in the buffer

Returns:: TRUE if successful, FALSE on error.

See also:: Burger::FileManager::SaveFileNative(const Burger::Filename *,const void *,WordPtr)

Word BURGER_API Burger::FileManager::SaveFileNative	(	const Burger::Filename *	pFileName,
		const void *	pInput,
		WordPtr	uLength
	)			`[static]`

Save a file using an OS native pathname.

Given an OS native pathname and a buffer, save the contents of the buffer into a file and close the file.

This function is a quick and easy way to write a buffer from memory directly to disk (Or any other storage medium).

Parameters:

	pFileName	Pointer to a Burger::Filename of an OS native path.
	pInput	Pointer to an array of bytes to save
	uLength	Number of bytes in the buffer

Returns:: TRUE if successful, FALSE on error.

See also:: Burger::FileManager::SaveFile(const char *,const void *,WordPtr)

Word BURGER_API Burger::FileManager::SaveTextFile	(	const char *	pFileName,
		const void *	pInput,
		WordPtr	uLength
	)			`[static]`

Save a text file.

Given a BurgerLib pathname and a buffer, save the contents of the buffer into a file and close the file.

This function is a quick and easy way to write a buffer from memory directly to disk (Or any other storage medium).

Note:: This differs from Burger::FileManager::SaveFile(const char *,const void *,WordPtr) in that all "\n" values will be translated to the proper line feeds for the target operating system. Unix and Linux, no change, Windows and MSDos, it's converted to a "\n\r", MacOS and MacOSX it's converted to "\r".

Parameters:

	pFileName	Pointer to a "C" string of a BurgerLib path.
	pInput	Pointer to an array of bytes to save as a text file.
	uLength	Number of bytes in the buffer

Returns:: TRUE if successful, FALSE on error.

See also:: Burger::FileManager::SaveTextFileNative(const Burger::Filename *,const void *,WordPtr)

Word BURGER_API Burger::FileManager::SaveTextFileNative	(	const Burger::Filename *	pFileName,
		const void *	pInput,
		WordPtr	uLength
	)			`[static]`

Save a text file using an OS native filename.

Given an OS native pathname and a buffer, save the contents of the buffer into a file and close the file.

This function is a quick and easy way to write a buffer from memory directly to disk (Or any other storage medium).

Note:: This differs from Burger::FileManager::SaveFile(const Burger::Filename *,const void *,WordPtr) in that all "\n" values will be translated to the proper line feeds for the target operating system. Unix and Linux, no change, Windows and MSDos, it's converted to a "\n\r", MacOS and MacOSX it's converted to "\r".

Parameters:

	pFileName	Pointer to a Burger::Filename of an OS native path.
	pInput	Pointer to an array of bytes to save as a text file.
	uLength	Number of bytes in the buffer

Returns:: TRUE if successful, FALSE on error.

See also:: Burger::FileManager::SaveTextFile(const const *,const void *,WordPtr)

Word BURGER_API Burger::FileManager::SetAuxType	(	const char *	pFileName,
		Word32	uAuxType
	)			`[static]`

Set a file's creator code.

On MacOS, a file has extended data which includes the application code that owns the file. This function will set the 4 byte code for the file.

On non MacOS platforms, this function will perform nothing..

Parameters:

	pFileName	Pointer to a "C" string of a BurgerLib pathname,
	uAuxType	Four byte character code to set.

Returns:: Non-zero if the file doesn't exist, the function isn't implemented of if the file doesn't have extended information. Zero if successful.

See also:: Burger::FileManager::SetAuxTypeNative(const Burger::Filename *,Word32), Burger::FileManager::SetFileType(const char *,Word32) or Burger::FileManager::SetFileAndAuxType(const char *,Word32,Word32)

Word BURGER_API Burger::FileManager::SetAuxTypeNative	(	const Burger::Filename *	pFileName,
		Word32	uAuxType
	)			`[static]`

Set a file's type code using a native filename.

On MacOS, a file has extended data which includes the file's type, which is independent of the filename. This function will set the 4 byte code for the file.

On non MacOS platforms, this function will perform nothing..

Parameters:

	pFileName	Pointer to a Burger::Filename of a native OS pathname,
	uAuxType	Four byte character code to set.

Returns:: Non-zero if the file doesn't exist, the function isn't implemented of if the file doesn't have extended information. Zero if successful.

See also:: Burger::FileManager::SetFileType(const char *,Word32), Burger::FileManager::SetAuxType(const char *,Word32) or Burger::FileManager::SetFileAndAuxType(const char *,Word32,Word32)

Word BURGER_API Burger::FileManager::SetFileAndAuxType	(	const char *	pFileName,
		Word32	uFileType,
		Word32	uAuxType
	)			`[static]`

Set a file's type and creator codes.

On MacOS, a file has extended data which includes the file's type, which is independent of the filename, and the creator code of the application that owns this file. This function will set the 4 byte codes for the file.

On non MacOS platforms, this function will perform nothing..

Parameters:

	pFileName	Pointer to a "C" string of a BurgerLib pathname,
	uFileType	A Word32 of the new file type code.
	uAuxType	A Word32 of the new file creator code.

Returns:: Non-zero if the file doesn't exist, the function isn't implemented of if the file doesn't have extended information. Zero is returned on successful completion.

See also:: Burger::FileManager::GetFileAndAuxTypeNative(const Burger::Filename *,Word32 *,Word32 *), Burger::FileManager::GetFileType(const char *) or Burger::FileManager::GetAuxType(const char *)

Word BURGER_API Burger::FileManager::SetFileAndAuxTypeNative	(	const Burger::Filename *	pFileName,
		Word32	uFileType,
		Word32	uAuxType
	)			`[static]`

Set a file's type and creator codes using a native filename.

On MacOS, a file has extended data which includes the file's type, which is independent of the filename, and the creator code of the application that owns this file. This function will set the 4 byte codes for the file.

On non MacOS platforms, this function will perform nothing..

Parameters:

	pFileName	Pointer to a Burger::Filename of a native OS pathname,
	uFileType	A Word32 of the new file type code.
	uAuxType	A Word32 of the new file creator code.

Returns:: Non-zero if the file doesn't exist, the function isn't implemented of if the file doesn't have extended information. Zero is returned on successful completion.

See also:: Burger::FileManager::GetFileAndAuxType(const char *,Word32 *,Word32 *), Burger::FileManager::GetFileType(const char *) or Burger::FileManager::GetAuxType(const char *)

Word BURGER_API Burger::FileManager::SetFileType	(	const char *	pFileName,
		Word32	uFileType
	)			`[static]`

Set a file's type code.

On MacOS, a file has extended data which includes the file's type, which is independent of the filename. This function will set the 4 byte code for the file.

On non MacOS platforms, this function will perform nothing..

Parameters:

	pFileName	Pointer to a "C" string of a BurgerLib pathname,
	uFileType	Four byte character code to set.

Returns:: Non-zero if the file doesn't exist, the function isn't implemented of if the file doesn't have extended information. Zero if successful.

See also:: Burger::FileManager::SetFileTypeNative(const Burger::Filename *,Word32), Burger::FileManager::SetAuxType(const char *,Word32) or Burger::FileManager::SetFileAndAuxType(const char *,Word32,Word32)

Word BURGER_API Burger::FileManager::SetFileTypeNative	(	const Burger::Filename *	pFileName,
		Word32	uFileType
	)			`[static]`

Set a file's type code using a native filename.

On MacOS, a file has extended data which includes the file's type, which is independent of the filename. This function will set the 4 byte code for the file.

On non MacOS platforms, this function will perform nothing..

Parameters:

	pFileName	Pointer to a Burger::Filename of a native OS pathname,
	uFileType	Four byte character code to set.

Returns:: Non-zero if the file doesn't exist, the function isn't implemented of if the file doesn't have extended information. Zero if successful.

See also:: Burger::FileManager::SetFileType(const char *,Word32), Burger::FileManager::SetAuxType(const char *,Word32) or Burger::FileManager::SetFileAndAuxType(const char *,Word32,Word32)

Word BURGER_API Burger::FileManager::SetPrefix	(	Word	uPrefixNum,
		const char *	pPrefixName
	)			`[static]`

Set the contents of a prefix.

Given a prefix number and a "C" string to a new pathname, set that prefix to the new value. The prefix is expanded BEFORE it's applied, so if you set prefix 10 with "10:foo" and prefix 10 was already ":Work:Temp:", then prefix 10 will result in ":Work:Temp:foo:"

Passing an empty string or a NULL will cause the prefix to be released and considered empty.

Parameters:

	uPrefixNum	Index to the requested prefix to obtain
	pPrefixName	Pointer to a "C" string of a new BurgerLib pathname

Returns:: Zero if no error, non-zero if error (Usually out of memory or out of bounds)

See also:: Burger::FileManager::GetPrefix(Burger::Filename *,Word)

void BURGER_API Burger::FileManager::Shutdown ( void ) [static]

Shut down the global file system manager.

Call this function once on shutdown to the burgerlib file manager. This function's primary purpose is to release all allocated memory and send out a report in case any files are still open on debug builds. The application is responsible for shutting down file usage before application shutdown.