The ReadDirectory() function is used to read directory content (files and
folders) according to your requirements. The resulting information is provided
in a convenient array that can be scanned for file names, sizes, permissions
and date stamps. The list can be automatically sorted for your
convenience.
This function will return an allocated array that you will need to free via
FreeMemory() once you are finished with it. The following table describes
the structure of each entry in the array:
*FileInfo | Next | Pointer to the next file entry in the list. |
STRING | Name | The name of the file or directory. |
STRING * | Tags | A list of special tag strings that are file-specific. |
LONG | Flags | Refer to the flags section for further information. |
LONG | Permissions | Standard permission flags. |
LARGE | Size | The size of the structure (note 64-bit quantity). |
FileTime | Time | Time structure, consists of Year, Month, Day, Hour, Minute and Second information. |
LARGE | TimeStamp | 64-bit time stamp - usable only for comparison (e.g. sorting). |
LONG | UserID | User ID (Unix systems only) |
LONG | GroupID | Group ID (Unix systems only) |
When calling the ReadDirectory() function you can specify a number of flags
that affect the function's behaviour. Certain flags are essential for receiving
optional information, such as the date and file permissions. Some of these
flags are also set in the Flags field of the FileInfo entries for informative
purposes. The following table indicates the available flag options.
RDF_ASSIGN | For the file list structure only. Indicates an assignment. |
RDF_DIRECTORY | List known folders in the directory. Also used to indicate folders in the file list. |
RDF_DATE | Retrieve the date and time stamp on each file. |
RDF_FILE | List known files in the directory. Also used to indicate files in the file list. |
RDF_LINK | Used in the FileList structure only. Indicates that the file or directory is actually a symbolic link. |
RDF_PERMISSIONS | Retrieve file permissions and the user/group ID. |
RDF_QUALIFY | Tells the function to produce fully qualified directory names (i.e. trailing slash or colon for each name). |
RDF_SIZE | Retrieve the byte size of each file. |
RDF_SORT | Sorts the results by name (ascending) |
RDF_TAGS | Receive additional information for each file, such as comments, author and copyright. The results are stored in the Tags array for each file, using the string format 'TAGNAME:Description' for each entry. |
The correct way to scan the resulting file list is to trawl the Next field
pointers until you run out of entries. Do not, under any circumstance, use indexes
to scan the array. The following example illustrates the correct way to scan the
list:
if (ReadDirectory("athene:", NULL, &fileinfo) IS ERR_Okay) {
for (list=fileinfo; list; list=list->Next) {
...
}
}
To retrieve a list of assignments (shortcuts) at the root level, use a Location string of ":".
ERR_Okay | Information was found in the directory and can be scanned from the resulting array. |
ERR_DirectoryEmpty | No information was found in the directory that matched your parameters. |
ERR_Args | Invalid arguments were specified. |
|