Classes | Static Public Member Functions | Static Public Attributes | Private Member Functions | Static Private Member Functions | Private Attributes | Static Private Attributes | Friends

Burger::FileManager Struct Reference

Global file system manager. More...

#include <fmfile.h>

Collaboration diagram for Burger::FileManager:
Collaboration graph
[legend]

List of all members.

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.

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

Friends And Related Function Documentation

friend class Filename [friend]

Member Data Documentation

const Word Burger::FileManager::DIRCACHESIZE = 8 [static, private]

Number of cache entries.

Global instance of the file manager.

True if MSDOS has long filename support (MSDOS Only).

char Burger::FileManager::m_BootName[256] [private]

Boot volume name in the format ":FooBar" (Not zero terminated) (MACOSX Only).

Directory cache (MAC Classic/Carbon Only).

Array of prefix strings.

Length of the boot volume name (MACOSX Only).

9: Directory where the application executable resides

"*:" Boot volume prefix number

8: Current working directory at application launch

const Word Burger::FileManager::PREFIXMAX = 35 [static]

Maximum number of pathname prefixes.

"@:" User preferences folder prefix number

"$:" System volume folder prefix number