FS_COMMAND_READDIR

定義

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

説明

アーカイブコマンド FS_COMMAND_READDIR の動作仕様を以下に示します。

このコマンドに渡される引数

p_file に格納された変数 arg.readdir をコマンド引数とします。 
この変数は nitro/fs/file.h にて以下のように定義されています。

typedef struct
{
    FSDirEntry  *p_entry;
    BOOL        skip_string;
} FSReadDirInfo;

引数の内容は以下のとおりです。

引数	内容
p_entry	ディレクトリエントリの情報を格納すべきFSDirEntry構造体へのポインタです。コマンドの結果を、このポインタの指すメモリへ格納します。
skip_string	この値が FALSE でない場合のみ、p_entry の name バッファに名前文字列を格納しなくても構いません。(格納しても構いません)

このコマンドに要求される動作

p_file は常に、prop.dir にディレクトリ位置情報を格納したハンドルです。
p_file の変数 prop.dir に基づいて以下のように設定します。

・引数の p_entry が指し示す FSDirEntry 構造体の各変数を正しく設定します。

  p_file が指す次のディレクトリエントリがファイル情報である場合は
  p_entry->is_directory に 0 を設定して p_entry->file_id にファイルIDを設定します。
  設定した値は、以降の FS_COMMAND_OPENFILEFAST コマンドで使用されます。

  p_file が指す次のディレクトリエントリがディレクトリ情報である場合は
  p_entry->is_directory に 1 を設定して p_entry->dir_id にディレクトリ位置を設定します。
  設定した値は、以降の FS_COMMAND_SEEKDIR コマンドで使用されます。

  いずれの場合も、p_entry->skip_string が FALSE であれば p_entry->name に
  ファイル名またはディレクトリ名を終端の '\0' も含めて格納します。
  また、この名前の長さを p_entry->name_len に設定します。


次のディレクトリエントリ情報が不正な場合、またはディレクトリ位置が終端の場合は何も行いません。
そうでない場合、上記設定を行ったのちに p_file のディレクトリ位置情報を次へ進めます。
この情報は、以降の FS_COMMAND_SEEKDIR コマンドおよび FS_COMMAND_READDIR コマンドで使用されます。

デフォルトの実装

以下の取り決めに基づいて値を設定します。

p_entry->is_directory	次のディレクトリエントリがファイルなら 0、ディレクトリなら 1
p_entry->file_id	ファイルID (次のディレクトリエントリがファイルの場合に限る) インデックスは prop.dir.index を指定
p_entry->dir_id	ディレクトリ位置 (次のディレクトリエントリがディレクトリの場合に限る) index = 0, pos = 0 によって先頭を指定
p_entry->name_len	次のディレクトリエントリの名前文字列長
p_entry->name	次のディレクトリエントリの名前文字列

これらの情報はアーカイブのFNTがNitroROMフォーマットに準拠していることを前提にして、
prop.dir.pos.pos で示されるFNTエントリブロックからアーカイブのリードコールバック関数を用いて取得します。

コマンドの結果

FS_RESULT_SUCCESS を返した場合、引数 p_entry の指すアドレスには
今回のディレクトリエントリが正しく格納されたと判断されます。
それ以外を返した場合、ディレクトリエントリの終端に達したかまたは
何らかのエラーにより列挙が中止されたと判断されます。
いずれの場合も、以降再び p_file に対してこのコマンドが呼ばれることがあります。

このコマンドが使用される関数

FS_ReadDir
( デフォルトの FS_FINDPATH コマンドから間接的に )
FS_ChangeDir
FS_OpenFile
FS_ConvertPathToFileID
( デフォルトの FS_GETPATH コマンドから間接的に )
FS_GetPathName
FS_GetPathLength

参照

FSArchive FS_ARCHIVE_PROC_FUNC FS_COMMAND_* FS_SetArchiveProc

履歴

2004/07/28 「skip_string が FALSE でなければ」を「skip_string が FALSE であれば」に修正
2004/07/12 初版