---

RtFSMgr
[File System]

Modules
Data Types
Functions
RwBool	RtFSManagerOpen (RwInt32 maxNbFS)
void	RtFSManagerClose (void)
RwBool	RtFSManagerSetCallBack (RtFSManagerCallBackCode cbCode, RtFSManagerCallBack CallBack)
RwBool	RtFSManagerRegister (RtFileSystem *fs)
void	RtFSManagerUnregister (RtFileSystem *fs)
RtFileSystem *	RtFSManagerGetFileSystemFromName (RwChar *fsName)
RtFile *	RtFSManagerFOpen (const RwChar *filename, RtFileAccessFlag access, RtFSFileOpCallBack CallBack, void *CallBackData)
RtFileSystem *	RtFSManagerGetFileSystemFromFileName (const RwChar *fileName)
void	RtFSManagerSetDefaultFileSystem (RtFileSystem *fs)
RtFileSystem *	RtFSManagerGetDefaultFileSystem (void)
void *	RwFopen (const RwChar *name, const RwChar *access)
RwInt32	RwFclose (void *fptr)
size_t	RwFread (void *addr, size_t size, size_t count, void *fptr)
size_t	RwFwrite (const void *addr, size_t size, size_t count, void *fptr)
RwInt32	RwFseek (void *fptr, long offset, RwInt32 origin)
RwChar *	RwFgets (RwChar *buffer, RwInt32 maxLen, void *fptr)
RwInt32	RwFputs (const RwChar *buffer, void *fptr)
RwInt32	RwFeof (void *fptr)
RwBool	RwFexist (const RwChar *name)
RwInt32	RwFtell (void *fptr)
RwBool	RwFAsyncCancel (RtFile *fptr)
void	RtFSManagerSyncAllFilesOnFileSystem (RtFileSystem *fs)
void	RtFSManagerSyncAllFiles (void)

---

Detailed Description

File System Manager.

RtFSMgr Overview

The RenderWare file system manager provides a generic interface through which all RenderWare I/O operations are undertaken. This constitutes the first layer of the file system API. It supports multiple file systems, each representing one device type. In other words it is designed to provide a common file transfer interface for all hardware devices.

The file system manager is responsible for managing the registration of new file systems, and for providing a generic file interface. This generic interface is an ANSI-C compliant interface that allows any RenderWare file operations to be done via the file system toolkit. As an example, a successful file open operation will involve looking for a registered file system, and calling the open function of the file system found.

---

Function Documentation

void RtFSManagerClose (  void    )

RtFSManagerClose closes the file system manager and frees all registered file systems. This function must be called when the application is about to be closed.

RtFile* RtFSManagerFOpen (  const RwChar *    filename, RtFileAccessFlag    access, RtFSFileOpCallBack    CallBack, void *    CallBackData )

RtFSManagerFOpen opens a file in a file system that is determined by the device name attached to the file name. This function will first try to get a file system device name from the file name specified. In the case where a corresponding file system is found (or a default file system has been registered), this function will look whether there are any available files in this file system. Remember that the maximum number of files a file system can concurrently handle is set during the file system initialization. If the file system still has any available file slots this function will then attempt to open the file. This function can be used directly to open a file when a file needs to be opened in asynchronous mode. In this case, you can use the RtFileAccessFlag enumeration to specify the correct file access. You can mix these flags using the binary OR operator as shown below: RtFileAccessFlag flags = 0; flags |= RTFILE_ACCESS_OPEN_READ; flags |= RTFILE_ACCESS_OPEN_ASYNC; To use this function, make sure that you have registered at least one file system. The function will automatically attempt to look for a file system from the file name so make sure that either your file names include the device name, or that you have registered a default file system (see RtFSManagerSetDefaultFileSystem). Note that it is generally common place to open a separate thread and use the file system in synchronous mode. This function should therefore be used only in the case where a file needs to be opened directly in asynchronous mode, and when the use of the internal asynchronous I/O mode is desired. Parameters: filename  Name of the file to open. access  Open access flags. CallBack  Asynchronous callback function. This callback will only be triggered for on completion of the current outstanding operation. CallBackData  Data passed to the callback function. Returns: NULL if failed, a pointer to a RtFile object if successful.

RtFileSystem* RtFSManagerGetDefaultFileSystem (  void    )

RtFSManagerGetDefaultFileSystem gets the current default file system Returns: The default file system or NULL if there is no default file system set.

RtFileSystem* RtFSManagerGetFileSystemFromFileName (  const RwChar *    fileName )

RtFSManagerGetFileSystemFromFileName Gets a registered file system from a complete file name, i.e. a file name including the device name. This function will look for the colon character (":") as a device separator. Also note that this function will automatically return the default file system (should one have been registered) in the case where it fails to find the correct file system as specified by the device name appended to the file name passed. Parameters: fileName  Full name of the file from which to retrieve the file system. Returns: A pointer to the corresponding file system or NULL if no corresponding file system has been found.

RtFileSystem* RtFSManagerGetFileSystemFromName (  RwChar *    fsName )

RtFSManagerGetFileSystemFromName gets a file system from its unique name. This function will return a pointer to the registered file system which has the unique name fsName. Note that fsName is user defined, and corresponds to the fileSystemName passed during the OS specific file system initialization. If no file system is found, the function will trigger the error callback with an RTFSM_ERROR_NOFS error, should an error callback be specified. Parameters: fsName  Name of the file system to retrieve. Returns: A pointer to the corresponding file system or NULL if no file system with the specified name has been registered.

RwBool RtFSManagerOpen (  RwInt32    maxNbFS )

RtFSManagerOpen opens and initializes the file system manager. This function performs all necessary operations to initialize the file system manager. This includes creating the file system manager, and installing a generic set of ANSI-C file functions to the standard RenderWare file interface. This function must be called first in order for any future file I/O operation to work through the file system toolkit. Parameters: maxNbFS  Maximum number of file systems the manager can handle, or RTFSMAN_UNLIMITED_NUM_FS for infinite. Returns: TRUE if successful, FALSE otherwise.

RwBool RtFSManagerRegister (  RtFileSystem *    fs )

RtFSManagerRegister registers a new file system with the file system manager. This function will perform some initial steps before actually registering the file system specified. It will first check whether the file system can be registered. This is done by checking whether the file system manager has reached its maximum capacity (which is specified during RtFSManagerOpen). If the maximum capacity has been reached, this function will return FALSE. However in the case where the manager can handle the new file system, this function will verify whether the unique name of the file system passed is not already in use. If that verification is successful, the function returns TRUE. In all other cases, it will return FALSE. Parameters: fs  Pointer to the file system to register. Returns: TRUE if sucessful, FALSE otherwise.

RwBool RtFSManagerSetCallBack (  RtFSManagerCallBackCode    cbCode, RtFSManagerCallBack    CallBack )

RtFSManagerSetCallBack sets a specific callback for the file system manager. This specific callback is determined by the callback code passed. Parameters: cbCode  Callback code. CallBack  Callback function. Returns: TRUE if sucessful, FALSE otherwise. See also: RtFSManagerCallBackCode

void RtFSManagerSetDefaultFileSystem (  RtFileSystem *    fs )

RtFSManagerSetDefaultFileSystem sets a default file system. The default file system is the file system that will be used as a last resort when trying to open a file. This means that when a file open operation is undertaken the manager will automatically try to use the default file system if no other valid file system, i.e. a file system corresponding to a possible device name specified in front of the file name to open, has been found. The file system manager allows you to set a default file system. This is particularly useful if your path names are relative or if you want to default any file I/O operations to a specific file system. Remember that when a file is opened, through the file system toolkit, a corresponding file system must be found. This means that if your paths are relative, they may not include any device name, and therefore a default file system must be registered in order for the open operation to be attempted. Parameters: fs  A pointer to the file system that will become the default file system

void RtFSManagerSyncAllFiles (  void    )

RtFSManagerSyncAllFiles will synchronise all the files on all the registered file systems.

void RtFSManagerSyncAllFilesOnFileSystem (  RtFileSystem *    fs )

RtFSManagerSyncAllFilesOnFileSystem will synchronise all the file on a particular file system, as well as trigger any callback for the current outstanding operations on the file within this file system. Parameters: fs  File system to synchronise.

void RtFSManagerUnregister (  RtFileSystem *    fs )

RtFSManagerUnregister unregisters a specific file system from the file system manager. This function checks that the file system passed is currently registered and, if it is, removes it from the list of file systems being managed by the file system manager. This will also involve freeing all memory associated with that file system. Should the file system specified be the default file system, this function will also reset the default file system to NULL. Note that if any files remain open when this function is called they will not be closed. In other words this function should not be called if the file system is still being used by any files. Should this be done it will result in an unpreditable behaviour, which will probably cause your program to crash. Parameters: fs  Pointer to the file system to unregister.

RwBool RwFAsyncCancel (  RtFile *    fptr )

RwFAsyncCancel cancels an asynchronous operation currently being undertaken on file handle "fptr". Parameters: fptr  File on which to cancel the operation on. Returns: TRUE if successful, FALSE otherwise.

RwInt32 RwFclose (  void *    fptr )

RwFclose closes the file associated with the file pointer fptr (ANSI-C compliant). Parameters: fptr  File pointer corresponding to the file to close. Returns: This function will return 0.

RwInt32 RwFeof (  void *    fptr )

RwFeof tests the end-of-file (EOF) indicator for the file specified by the file pointer "fptr" (ANSI-C compliant). Parameters: fptr  File pointer corresponding to the file to test for EOF. Returns: 1 if EOF, 0 otherwise.

RwBool RwFexist (  const RwChar *    name )

RwFexist checks whether a file specified by its name exists. Parameters: name  Name of the file. Returns: TRUE if the file exists, FALSE otherwise.

RwChar* RwFgets (  RwChar *    buffer, RwInt32    maxLen, void *    fptr )

RwFgets reads at most (maxLen - 1) characters from the file specified by the file pointer "fptr", and stores them in the string "buffer" (ANSI-C compliant). Parameters: buffer  String holding the characters read. maxLen  Maximum number of characters to read. fptr  File pointer corresponding to the file to read. Returns: A pointer to the string read if successful, 0 otherwise.

void* RwFopen (  const RwChar *    name, const RwChar *    access )

RwFopen opens a file. This is an ANSI-C compliant function allowing the use of standard file access flags, i.e. valid combinations of 'r', 'w', 'b', and 'a'. This function calls RtFSManagerFOpen. Parameters: name  Name of the file. access  File access flags. Returns: A pointer to the file opened or NULL if the file couldn't be opened. RtFSManagerFOpen

RwInt32 RwFputs (  const RwChar *    buffer, void *    fptr )

RwFputs writes the string pointed by "buffer" to the file specified by the file pointer "fptr" (ANSI-C compliant). Parameters: buffer  String holding the characters to write. fptr  File pointer corresponding to the file to write to. Returns: The total number of bytes written if successful, 0 otherwise.

size_t RwFread (  void *    addr, size_t    size, size_t    count, void *    fptr )

RwFread reads "count" objects each of size "size" from the file associated with the file pointer "fptr", and stores the data read at the location given by "addr" (ANSI-C compliant). Parameters: addr  Buffer into which the data read will be stored. size  Number of bytes to read. count  Number of objects of size "size" to read. fptr  File pointer corresponding to the file to read from. Returns: The number of object(s) read.

RwInt32 RwFseek (  void *    fptr, long    offset, RwInt32    origin )

RwFseek sets the file position to the appropriate offset and from a specific origin (ANSI-C compliant). The new position (in bytes) is obtained by adding the offset "offset" to the position specified by "origin". Parameters: fptr  File pointer corresponding to the file to set the position to. offset  Number of bytes corresponding to the new position within the file. origin  Position form which the offset will be applied. Returns: 0 if successful, -1 otherwise.

RwInt32 RwFtell (  void *    fptr )

RwFtell returns the current position of the file specified by file pointer "fptr". Parameters: fptr  File to get the position from. Returns: Current position of the file.

size_t RwFwrite (  const void *    addr, size_t    size, size_t    count, void *    fptr )

RwFwrite writes "count" objects (obtained from the location given by the pointer "addr") each of size "size" from the file associated with the file pointer "fptr" (ANSI-C compliant). Parameters: addr  Buffer from which the data written is taken. size  Number of bytes to write. count  Number of objects of size "size" to write. fptr  File pointer corresponding to the file to write to. Returns: The number of object(s) written.

---