# 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 an 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 | When this value is not FALSE, a name character string does not need to be stored in the `p_entry`'s name buffer. (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 (used only if the next directory entry is a directory) The top is set by `index = 0`, `pos = 0`.
p_entry->name_len | Name character string length of the next directory entry.
p_entry->name | Name character 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

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

CONFIDENTIAL