FS_COMMAND_READDIR

Definition


FSResult FS_ARCHIVE_PROC_FUNC(FSFile *p_file, FSCommandType command /* = FS_COMMAND_READDIR */);

Description

Operating specifications for the archive command FS_COMMAND_READDIR are shown below:

Arguments passed to this command 
This command takes as a command argument the variable arg.readdir that is stored in p_file. 
This variable is defined in nitro/fs/file.h as shown below:
typedef struct
{
    FSDirEntry  *p_entry;
    BOOL        skip_string;
} FSReadDirInfo;
Argument content is listed below:
Arguments Content
p_entry Pointer to the FSDirEntry structure that stores directory information.
Command results are stored in the memory that is indicated by this pointer.
skip_string If this value is not FALSE, the name string does not have to be stored in the name buffer of p_entry. (It can be stored as well.)

Actions required of this command 
p_file is a handle that always holds directory position information in prop.dir.
Based on p_file's prog.dir variable, the command makes the following settings:
It correctly sets each variable in the FSDirEntry structure that is identfied by the p_entry argument.
  If the next directory entry indicated by p_file is file information,
  it sets p_entry->is_directory to 0, and sets the file ID in p_entry->file_id.
  These set values are used by subsequent FS_COMMAND_OPENFILEFAST commands.
  If the next directory entry indicated by p_file is directory information,
  it sets p_entry->is_directory to 1, and sets the directory position in p_entry->dir_id.
  These set values are used by subsequent FS_COMMAND_SEEKDIR commands.
  In either case, if p_entry->skip_string is FALSE,
  it will store the file name or directory name, including the terminating '\0' in p_entry->name.
  It will also set the length of the name in p_entry->name_len.
If the next directory entry information is invalid, or if the directory position is a terminator, the command does nothing.
Otherwise, after setting the above, it will advance to the next p_file directory position information.
Subsequently, this information is used by the FS_COMMAND_SEEKDIR and FS_COMMAND_READDIR commands.
Default Implementation
The command sets values based on the following determinants:
p_entry->is_directory If the next directory is a file, 0; if it is a directory, 1.
p_entry->file_id File ID (only if the next directory entry is a file)
Index is set as prop.dir.index.
p_entry->dir_id Directory position (only if the next directory entry is a directory)
The top is set by index = 0, pos = 0.
p_entry->name_len Name string length of the next directory entry.
p_entry->name Name string of the next directory entry.
As long as the archive's FNT conforms to the NitroROM format (determined by using the archive read callback function), this information is acquired from the FNT entry block that is indicated by prop.dir.pos.pos.
Command Results
If FS_RESULT_SUCCESS is returned by the command, then the current directory entry has been properly stored at the address indicated by the argument p_entry.
 
If anything else is returned, it is determined that the end of the diretory entries was reached, or
the listing was stopped due to some type of error.

 In either case, this command can be called again later for p_file.
Functions that use this command
FS_ReadDir (indirectly from the default FS_FINDPATH command)
FS_ChangeDir
FS_OpenFile
FS_ConvertPathToFileID (indirectly from the default FS_GETPATH command)
FS_GetPathName
FS_GetPathLength

See Also

FSArchive
FS_ARCHIVE_PROC_FUNC
FS_COMMAND_*
FS_SetArchiveProc

Revision History

2004/07/28 Revised "if skip_string is not FALSE" to "if skip_string is FALSE"
2004/07/12 Initial Version

CONFIDENTIAL