Mini File System Library Documentation

Copyright (c) 2001-2003 Pu Bo

Copyright (c) 2003 Wang Zheng

All rights reserved

0. Introduction

0.1 Installation

1. Function documentation

FSErr ChangeCurDir(const char far *pathName)

unsigned short GetDirFileNumber(FileHndl dir)

void GetFileName(FileHndl dir,unsigned short fileIdx,char far *fileName)

bool IsDir(FileHndl dir,unsigned short fileIdx)

bool IsFileDir(FileHndl fileH)

FileHndl MakeDir(const char far *name)

FileHndl FileOpen(const char far *name,FileOpenMode mode)

unsigned long FileRead(FileHndl fileH,MemHndl bufH,unsigned long size)

unsigned long FileWrite(FileHndl fileH,MemHndl bufH,unsigned long size)

FSErr FileSeek(FileHndl fileH,unsigned long pos)

unsigned long FileTell(FileHndl fileH)

unsigned long GetFileSize(FileHndl fileH)

void FileClose(FileHndl fileH)

FSErr DeleteFile(const char far *pathName)

FSErr GetLastError()

const char far *GetCurrentDirectory()

void FileSysManagement()

void TrimFile(FileHndl fileH)

FSErr FileRename(const char far *srcPath,const char far *destPath)

void FileSysSetMgmtProgressCB(FileMgmtProgressCBFunc cb)

unsigned long FileSysAvailableStorage()

0. Introduction

Mini File System is a file system for CASIO pocket viewer. It is a Unix style file system, that organize files in a tree of directories. The root of the tree is "root directory" which has a name "/". '/' also is the path seperator (e.g. "/MiniBook/Res/de.res" is the path name of the file, whose name is "de.res" and resides in the directory "Res". The directory "Res" resides in directory "MiniBook". The directory "MiniBook" resides in root directory. ).

There are already several PV applications benifits from MFS, e.g. MiniBook 2.5x, MFSTool. Mini File System Library is a library module that enables PV developers to use MFS in their application.

0.1 Installation

Since MiniFS.lib has integrated MemMgr.lib, and MemPool.lib, you need to uninstall them if previously installed.

To do so:
Remove the corresponding lines from link2p.dat file.

To install MFS Lib:

  1. Unzip the package

  2. Copy MiniFS.lib to your library folder

  3. Copy all .h files to your include folder

  4. Change your makefile to link the library

(For example of installing library, please refer to http://groups.yahoo.com/group/minibook/files/Development/DevFrameWork.zip)

1. Function documentation

Before you can use any MFS functions, please make sure that you have created memory pool.

To Create memory pool:

  1. #include "FileSys.h"

  2. Define a global array of byte to be used as memory pool. Call MemMgrInit() at the begining of main() function.

e.g.

static byte far _memPool[1024*20];

...

void main()

{

    MemMgrInit(_memPool,sizeof(_memPool));

    ...

}

It is recommanded to create a memory pool as large as possible. (Normally, should not be less than 10 k). Using MemMgr to allocate memory in rest of your program is encouraged.

FSErr ChangeCurDir(const char far *pathName)

Parameters:

Return:

FSNoErr if no error, else error code

Description:

This function change current directory to specified directory. Current directory is used to interpret relative path name. There are two kinds of pathname

  1. Absolute path name: starts from '/', e.g. "/MiniBook/Res/de.res". It is the path from root directory to the specified file or directory.
  2. Relative path name: starts from non-'/' character, e.g. "Res/de.res". It is the path from current directory to the specified file or directory. If current directory is "/MiniBook", the example here specifies the same file as example in 1.

There are two special path name:

  1. "." this is the current directory.
  2. ".." this is the parent directory of current directory. The parent directory of root directory is root directoy.

unsigned short GetDirFileNumber(FileHndl dir)

Parameters:

Return:

Number of files in the directory, including "..". If the file handle is not a directory, returns 0.

Description:

Get number of files and directories in the directory. Each directory contains at least 1 directory: "..". Therefore, a 0 return value means the file handle passed in is not a directory.

void GetFileName(FileHndl dir,unsigned short fileIdx,char far *fileName)

Parameters:

Return:

None.

Description:

Get number of files and directories in the directory. Each directory contains at least 1 directory: "..". Therefore, a 0 return value means the file handle passed in is not a directory.

bool IsDir(FileHndl dir,unsigned short fileIdx)

Parameters:

Return:

TRUE if the file is directory, else FALSE

Description:

Check whether a file in the specified directory is a directory. This function is used to check a file's attribute without open that file.

bool IsFileDir(FileHndl fileH)

Parameters:

Return:

TRUE if the file is directory, else FALSE

Description:

Check whether a file is a directory. This function is used to check a opened file's attribute.

FileHndl MakeDir(const char far *name)

Parameters:

Return:

If success, it opens the created directory as kFSReadOnly (directory can only be openned as kFSReadOnly), and returns the file handle of the created directory. If fail, it returns NULL.

Description:

Create directory of the specified path name.

FileHndl FileOpen(const char far *name,FileOpenMode mode)

Parameters:

Return:

If success, it opens the file, and returns the. If fail, it returns NULL.

Description:

Open a file in specified mode.

NOTE:

It is important that all opened files/directories are closed at the program exit. Otherwise, all RAM cached data will be lost, and it could cause file system corrupt.

unsigned long FileRead(FileHndl fileH,MemHndl bufH,unsigned long size)

Parameters:

Return:

Number of bytes actually read.

Description:

Read a file from current file access point. After read, the file access point is increased by number of bytes actually read.

unsigned long FileWrite(FileHndl fileH,MemHndl bufH,unsigned long size)

Parameters:

Return:

Number of bytes actually written.

Description:

Write a file from current file access point. If current access point is the end of the file, the file will be expanded to allow data to be written. After write, the file access point is increased by number of bytes actually written.

FSErr FileSeek(FileHndl fileH,unsigned long pos)

Parameters:

Return:

FSNoErr if success, else the error code.

Description:

Set the file access point of the specified file. If fail, the access point is not changed.

unsigned long FileTell(FileHndl fileH)

Parameters:

Return:

Value of current access point.

Description:

Get the file access point of the specified file.

unsigned long GetFileSize(FileHndl fileH)

Parameters:

Return:

Size of the file in number of bytes.

Description:

Get the file size.

void FileClose(FileHndl fileH)

Parameters:

Return:

None.

Description:

Close the file.

NOTE:

After the file is closed, the fileH is invalid, therefore it should not be used in any file functions, otherwise, it may corrupt the file system.

FSErr DeleteFile(const char far *pathName)

Parameters:

Return:

FSNoErr if success, else the error code.

Description:

Delete a file.

NOTE:

If the file is open, it must be closed before it can be deleted, otherwise, it may corrupt the file system.

FSErr GetLastError()

Parameters:

None.

Return:

Error code of last file system function.

Description:

Use this function to get the error code, if the file function does not return error code (e.g. FileRead())

const char far *GetCurrentDirectory()

Parameters:

None.

Return:

Current directory's absolute path name.

Description:

Get the absolute path name of current directory. Since the string is dynamiclly allocated and maintained by file system, it should be used immediatly after call this function. If you store this pointer in a variable, you must make sure that between you call the function and you use the stored pointer, there is no function call that could cause memory purge. Almost all file system functions may cause memory purge. Therefore, it is recommanded that you call this function at the place you use the retruned pointer.

void FileSysManagement()

Parameters:

None.

Return:

None.

Description:

Perform file system management. This will release all unused (deleted) blocks, and do a pocket viewer memory management. It may take a long time.

void TrimFile(FileHndl fileH)

Parameters:

Return:

None.

Description:

Remove data that after current access point from the file. This is the only function that could reduce the file's size.

FSErr FileRename(const char far *srcPath,const char far *destPath)

Parameters:

Return:

FSNoErr if success, else the error code.

Description:

Rename a file or directory.

void FileSysSetMgmtProgressCB(FileMgmtProgressCBFunc cb)

Parameters:

Return:

None

Description:

specify a callback function for the file system management process. The prototype of the callback is

typedef bool (*FileMgmtProgressCBFunc)(unsigned long maxVal, unsigned long curVal);

the process has two steps:

The callback function returns TRUE to continue the file system management, it returns FALSE to terminate the process.

unsigned long FileSysAvailableStorage()

Parameters:

None

Return:

Number of bytes available in the file system.

Description:

Get the number of bytes available in the file system.