# FS_COMMAND_READDIR

## C Specification

      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` | Unless this value is `FALSE`, you must store name character strings in the `p_entry`'s name buffer.

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 that `p_file` points to 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 by the command, then listing was aborted because the directory entry terminator arrived, or because of some 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