1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> 2<html> 3<head> 4<META http-equiv="Content-Type" content="text/html; charset=windows-1252"> 5<META name="GENERATOR" content="IBM WebSphere Studio Homepage Builder Version 8.0.0.0 for Windows"> 6<META http-equiv="Content-Style-Type" content="text/css"> 7<title>FS_COMMAND_READDIR</title> 8<LINK rel="stylesheet" href="../../css/nitro.css" type="text/css"> 9</head> 10<body> 11<h1 align="left">FS_COMMAND_READDIR <img src="../../image/NTR.gif"align="middle"><img src="../../image/TWL.gif" align="middle"></h1> 12<h2>Definition</h2> 13<dl> 14 <dd> 15<BR> <CODE>FSResult FS_ARCHIVE_PROC_FUNC(FSFile *p_file, FSCommandType command /* = FS_COMMAND_READDIR */);<br></CODE><br> 16 </dd> 17</dl> 18<H2>Description</H2> 19<P>Operating specifications for the archive command <code>FS_COMMAND_READDIR</code> are shown below: <BR> <BR> 20<HR> 21<B>Arguments passed to this command</B> 22<BLOCKQUOTE> 23<PRE>This command takes as a command argument the variable <code>arg.readdir</code> that is stored in <code>p_file</code>. 24This variable is defined in <code>nitro/fs/file.h</code> as shown below: 25typedef struct 26{ 27 <a href="../fs_dir_entry_type.html">FSDirEntry</a> *p_entry; 28 BOOL skip_string; 29} FSReadDirInfo;</code> </PRE> 30</BLOCKQUOTE> 31<BLOCKQUOTE>Argument content is listed below: 32</BLOCKQUOTE> 33<CENTER> 34<TABLE border="1" width="50%"> 35 <TBODY> 36 <TR> 37<TD style="text-align : center;" width="95">Arguments</TD> 38<TD style="text-align : center;" width="522">Content</TD> 39 </TR> 40 <TR> 41<TD width="95" style="text-align : center;">p_entry</TD> 42<TD width="522">Pointer to the <code><a href="../fs_dir_entry_type.html">FSDirEntry</a></code> structure that stores directory information.<br />Command results are stored in the memory that is indicated by this pointer.</TD> 43 </TR> 44 <TR> 45<TD style="text-align : center;">skip_string</TD> 46<TD>If this value is not FALSE, the name string does not have to be stored in the <CODE>name</CODE> buffer of <CODE>p_entry</CODE>. (It can be stored as well.)</TD> 47 </TR> 48 </TBODY> 49</TABLE> 50</CENTER> 51<BR> 52<HR> 53<B>Actions required of this command</B> 54<BLOCKQUOTE> 55<PRE><code>p_file</code> is a handle that always holds directory position information in <code>prop.dir</code>. 56Based on <code>p_file</code>'s <code>prog.dir</code> variable, the command makes the following settings: 57It correctly sets each variable in the <code><a href="../fs_dir_entry_type.html">FSDirEntry</a></code> structure that is identfied by the <code>p_entry</code> argument. 58 If the next directory entry indicated by p_file is file information, 59 it sets <code>p_entry->is_directory</code> to 0, and sets the file ID in <code>p_entry->file_id</code>. 60 These set values are used by subsequent <code><a href="fs_command_openfilefast_spec.html">FS_COMMAND_OPENFILEFAST</a></code> commands. 61 If the next directory entry indicated by p_file is directory information, 62 it sets <code>p_entry->is_directory</code> to 1, and sets the directory position in <code>p_entry->dir_id</code>. 63 These set values are used by subsequent <code><a href="fs_command_seekdir_spec.html">FS_COMMAND_SEEKDIR</a></code> commands. 64 In either case, if <code>p_entry->skip_string</code> is FALSE, 65 it will store the file name or directory name, including the terminating '<code>\0</code>' in <code>p_entry->name</code>. 66 It will also set the length of the name in <code>p_entry->name_len</code>. 67If the next directory entry information is invalid, or if the directory position is a terminator, the command does nothing. 68Otherwise, after setting the above, it will advance to the next <code>p_file</code> directory position information. 69Subsequently, this information is used by the <code><a href="fs_command_seekdir_spec.html">FS_COMMAND_SEEKDIR</a></code> and <code><a href="fs_command_readdir_spec.html">FS_COMMAND_READDIR</a></code> commands.</PRE> 70</BLOCKQUOTE> 71<HR> 72<B>Default Implementation</B> 73<BLOCKQUOTE>The command sets values based on the following determinants: 74</BLOCKQUOTE> 75<CENTER> 76<TABLE border="1"> 77 <TBODY> 78 <TR> 79<TD width="185">p_entry->is_directory</TD> 80<TD width="432">If the next directory is a file, <code>0</code>; if it is a directory, <code>1</code>.</TD> 81 </TR> 82 <TR> 83<TD width="185">p_entry->file_id</TD> 84<TD width="432">File ID (only if the next directory entry is a file)<br /> Index is set as <code>prop.dir.index</code>.</TD> 85 </TR> 86 <TR> 87<TD width="185">p_entry->dir_id</TD> 88<TD width="432">Directory position (only if the next directory entry is a directory)<br /> The top is set by <code>index = 0</code>, <code>pos = 0</code>.</TD> 89 </TR> 90 <TR> 91<TD width="185">p_entry->name_len</TD> 92<TD width="432">Name string length of the next directory entry.</TD> 93 </TR> 94 <TR> 95<TD>p_entry->name</TD> 96<TD>Name string of the next directory entry.</TD> 97 </TR> 98 </TBODY> 99</TABLE> 100</CENTER> 101<BLOCKQUOTE>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 <code>prop.dir.pos.pos</code>. 102</BLOCKQUOTE> 103<HR> 104<B>Command Results</B><BR> 105<BLOCKQUOTE> 106<PRE>If <code>FS_RESULT_SUCCESS</code> is returned by the command, then the current directory entry has been properly stored at the address indicated by the argument <code>p_entry</code>. 107 108If anything else is returned, it is determined that the end of the diretory entries was reached, or 109the listing was stopped due to some type of error. 110<br /> In either case, this command can be called again later for <code>p_file</code>. 111</PRE> 112</BLOCKQUOTE> 113<HR> 114<B>Functions that use this command</B><BR> 115<BLOCKQUOTE><a href="../file/FS_ReadDir.html"><code>FS_ReadDir</code></a> (indirectly from the default <a href="fs_command_findpath_spec.html"><code>FS_FINDPATH</code></a> command)<BR><code>FS_ChangeDir</code><BR><code>FS_OpenFile</code> <BR><a href="../file/FS_ConvertPathToFileID.html"><code>FS_ConvertPathToFileID</code></a> (indirectly from the default <a href="fs_command_getpath_spec.html"><code>FS_GETPATH</code></a> command)<BR><code>FS_GetPathName</code> <BR><code>FS_GetPathLength</code></BLOCKQUOTE> 116<h2>See Also</h2> 117<p><code><a href="../fs_archive_type.html">FSArchive</a></code><BR> <code><a href="../fs_archive_proc_func_type.html">FS_ARCHIVE_PROC_FUNC</a></code><BR> <code><a href="../fs_command_type_const.html">FS_COMMAND_*</a></code><BR> <code><a href="../archive/FS_SetArchiveProc.html">FS_SetArchiveProc</a></code></p> 118<H2>Revision History</H2> 119<P> 1202004/07/28 Revised "if <code>skip_string</code> is not <code>FALSE</code>" to "if <code>skip_string</code> is <code>FALSE</code>"<br /> 2004/07/12 Initial Version 121</P> 122<hr><p>CONFIDENTIAL</p></body> 123</html> 124
