3． directory operations

3.1 Initialization

GFS_Init must be executed before using this library. GFS_Init performs the following processing.

• Library work area initialization
• Mounting process

(1) Initialization

Sets the work area used by the library and initializes it. All work areas and directory information storage areas must be provided by the application.
The size of that area changes depending on the number of files opened at the same time, so use the following macro to find it. Here open_max is the maximum number of files to open at the same time.

GFS_WORK_SIZE(open_max)

(2)Mount processing

Reads the root directory from the CD-ROM and sets it as the current directory. It also initializes the CD block and deletes all sector data in the CD buffer. Since the file system only holds the start address of the directory information storage area, applications must not change the contents of the area.
Initialize the directory information management structure and call GFS_Init as follows.

#define OPEN_MAX 20 /* Maximum number of files to open simultaneously */
#define MAX_DIR 10 /* Maximum number of directory information */

Uint32 work[GFS_WORK_SIZE(OPEN_MAX)/4]; /* Library work area */
GfsDirTbl dirtbl; /* Directory information management structure */
GfsDirId dir[MAX_DIR]; /* Directory information storage area */

GFS_DIRTBL_TYPE(&dirtbl) = GFS_DIR_ID; /* Directory information storage area type */
GFS_DIRTBL_NDIR(&dirtbl) = MAX_DIR; /* Directory information storage area */
                                           /* Maximum number of elements */
GFS_DIRTBL_DIRID(&dirtbl) = dir; /* Directory information storage area */
                                           /* address */
GFS_Init(OPEN_MAX, work, &dirtbl);

If you change the CD-ROM, you must call GFS_Init again.

3.2 File identifier

This library assumes that files to be accessed are specified by file identifiers.
When accessing by file name, convert the file name to a file identifier.
File identifiers are valid for the current directory.

[Example] When accessing the following FILE2.DAT

Figure 3.1 Access by file identifier

3.3 Subdirectory operations

To access files in subdirectories, you need to set the current directory information by calling the following function.

• Load directory information (GFS_LoadDir)
• Current directory setting (GFS_SetDir)

It can be used to read directory information in advance and eliminate CD-ROM access when opening a file.

(1) Loading directory information (GFS_LoadDir)

Loads and maintains directory information by specifying subdirectory files.
At this time, the following two types can be selected as the directory information holding area.

(a)GFS_DIR_ID

• Does not preserve file names. Access is only possible by file identifier.

(b)GFS_DIR_NAME

• It holds file names, so requires more space than (a).
• Access by file name is possible.

(2) Setting the current directory (GFS_SetDir)

The directory information area read by GFS_LoadDir is set as the current directory.

Figure 3.2 Directory information settings

To access files in subdirectories you must follow these steps:

Load directory information
↓
Current directory setting
↓
Open file
↓
Access to files
↓
Close file

We illustrate this procedure with two examples.

[Example] Accessing files in directories other than the root directory

The following is a program example of the procedure for accessing files in subdirectories. Assume that the file you want to access is located in the directory specified by dir_fid in the current directory.

#define MAX_DIR 10 /* Maximum number of directory information */

GfsDirTbl dirtbl; /* Directory information storage area */
GfsDirId dirid[MAX_DIR]; /* Directory information storage area */
Sint32 dir_fid; /* Contains the directory file identifier */
Sint32 fid; /* Contains the identifier of the file to be accessed */
GfsHn gfs; /* File handle of the file to access */

GFS_DIRTBL_TYPE (&dirtbl) = GFS_DIR_ID;
GFS_DIRTBL_NDIR (&dirtbl) = MAX_DIR;
GFS_DIRTBL_DIRID(&dirtbl) = dirid;

GFS_LoadDir(dir_fid, &dirtbl); /* Load directory information */

GFS_SetDir(&dirtbl); /* Set current directory */

/* Set the identifier of the file to access fid */
gfs = GFS_Open(fid);
/*
 * File access here */
GFS_Close(gfs);

[Example] Simultaneous access to multiple files in different directories

To access files in different directories, you must open the desired file while switching the current directory.
Here is an example of accessing two files in two subdirectories directly under the current directory at the same time. Assume that the file identifiers of the two subdirectories containing the files you want to access are specified by dir_fid1 and dir_fid2, respectively.

#define MAX_DIR1 10 /* Maximum number of directory information for dir_fid1 */
#define MAX_DIR2 10 /* Maximum number of directory information for dir_fid2 */

GfsDirTbl curdir; /* Current directory at this point */
GfsDirTbl dirtbl1, dirtbl2; /* Directory information management area */
GfsDirId dirid1[MAX_DIR1]; /* Directory information storage area */
GfsDirId dirid2[MAX_DIR2]; /* Directory information storage area */
Sint32 dir_fid1, dir_fid2; /* Contains the directory file identifier */
Sint32 fid1, fid2; /* Contains the identifier of the file to be accessed */
GfsHn gfs1, gfs2; /* File handle of the file to access */

/* Read the directory information of dir_fid1 in the current directory */
GFS_DIRTBL_TYPE (&dirtbl1) = GFS_DIR_ID;
GFS_DIRTBL_NDIR (&dirtbl1) = MAX_DIR;
GFS_DIRTBL_DIRID(&dirtbl1) = dirid1;
GFS_LoadDir(dir_fid1, &dirtbl1);

/* Read the directory information of dir_fid2 in the current directory */
GFS_DIRTBL_TYPE (&dirtbl2) = GFS_DIR_ID;
GFS_DIRTBL_NDIR (&dirtbl2) = MAX_DIR;
GFS_DIRTBL_DIRID(&dirtbl2) = dirid2;
GFS_LoadDir(dir_fid2, &dirtbl2);

/* Open file fid1 in directory dir_fid1 */
GFS_SetDir (&dirtbl1);
gfs1 = GFS_Open(fid1);

/* Open file fid2 in directory dir_fid2 */
GFS_SetDir (&dirtbl2);
gfs2 = GFS_Open(fid2);
/*
 * File access here */
GFS_Close(gfs1);
GFS_Close(gfs2);

3.4 Mutual conversion between file name and file identifier

If you set directory information that includes file names in the current directory, you can use the mutual conversion function between file names and file identifiers.
If you call these functions while the current directory is set to directory information that does not include a file name, an error will occur.
Here is an example definition of a function that uses this feature to open a file by file name.

[Example] /* Open the file specified by file name */
GfsHn OpenByName(Sint8 *fname)
{
Sint32 fid = GFS_NameToId(fname);

if (fid＜ 0) {
return NULL;
}
return GFS_Open(fid);
}

3.5 CD Block File System

Directories can be managed using the CD Block file system (a file system built into the CD Block, hereinafter abbreviated as CDBFS).
The following describes the process for initializing, reading directory information, and setting the current directory using CDBFS.

(1) Initialization

To use the CDBFS functionality, you must call GFS_Init with NULL specified as the pointer to the directory management structure. After GFS_Init processing completes, the root directory is set in CDBFS.

(2) Reading directory information

To load subdirectory information, call GFS_LoadDir with a NULL pointer to the directory management structure and specify that the directory information is to be stored in the CD block.

(3)Current directory setting

To set the directory information set in the CD block to the current directory, call GFS_SetDir with NULL specified as the pointer to the directory management structure.

Even if you configure settings to use CDBFS, it is possible to partially manage directories with this library. In this case, you should always be careful about which directory management facility you are using.
Table 3.1 shows the advantages and disadvantages of using CDBFS.

Table 3.1 Advantages and disadvantages of using CDBFS

Strong Points	Cons
- Less host memory usage.	・Access files in different directories CD-ROM access occurs every time the To do.
	・CD back that can be used by the application Fa is reduced by 1 section.
	- File name cannot be used.

The functions GFS_Init and GFS_LoadDir that read directory information return the number of pieces of directory information read as a function value. When using CDBFS, the number is the number of directory information held by CDBFS.
If you use a file name while setting the CDBFS current directory, an error will occur.