Directory scan


Section contents


Overview

Defined in

cfile.oxh

Description

Use this class to scan a directory structure. The scan moves from directory to directory through the hierarchy, returning a list of the entries contained in each. The order in which the directories are scanned is determined by a sort key which is specified when setting up the scan. The base directory to be scanned and the entry types of interest must also be specified before performing the scan.


Construction / destruction


DeleteDirScan - Destructor

Usage

DeleteDirScan:(BYREF this&)

Description

Destroys the directory scan object.

Arguments
BYREF this& A handle to a directory scan object

DirScanNew - Allocate and construct

Usage

DirScanNew:(fs&)

Description

Use this function to construct and allocate memory for a new DirScan object.

Arguments
fs& A handle to a file system object
Error Handling

If the object could not be created then an error is generated which should be trapped by an ONERR handler.


Methods provided


DirScanAbbreviatedPath - get abbreviated path

Usage

path$ = DirScanAbbreviatedPath$:(this&)

Description

Use this function to get the abbreviated path of the entry currently being scanned. The abbreviated path is the path relative to the top level directory in the scan.

Arguments
this& A handle to a directory scan object
scanList& On return, contains filtered entries from the next directory in the structure. Returns NULL when all entries in the structure have been scanned.
Return value
path& The abbreviated path of the entry currently being scanned.

DirScanFullPath - get absolute path

Usage

path$ = DirScanFullPath$:(this&)

Description

Use this function to get the full path of the entry currently being scanned. The full path is the absolute path, including the drive letter.

Arguments
this& A handle to a directory scan object
scanList& On return, contains filtered entries from the next directory in the structure. Returns NULL when all entries in the structure have been scanned.
Return value
path& The absolute path of the entry currently being scanned..

DirScanNext - scan next directory

Usage

DirScanNext:(this&,BYREF dirList&)

Description

Use this function to move to the next directory entry in the structure. The order in which the structure is scanned is determined by the scan direction and the entry sort mask which are specified when setting up the scan. The type of entries returned by this function is determined by the entry attribute mask also specified when setting up the scan.

Arguments
this& A handle to a directory scan object
scanList& On return, contains filtered entries from the next directory in the structure. Returns NULL when all entries in the structure have been scanned.
Error Handling

If the next directory cannot be created then an error is generated which should be trapped by an ONERR handler.


DirScanSetScanData - set up the scan

Usage

DirScanSetScanData:(this&,name$,attMask&,sortMask&,scanDirection%)

Description

Use this function to set up the scan. This involves specifying the directory at the top of the structure to be scanned, a filter for the entry types of interest, the order in which the entries in each directory in the structure are to be sorted and the scan direction.

Whether the scan direction is upwards or downwards, the directories which are scanned are those in the part of the hierarchy below the directory specified in aMatchName. By default, the scan direction is downwards. If the scan direction is set to KDirScanScanUpTree, all branches of the tree are explored starting at the lowest level directory in the tree below aMatchName, and ending at aMatchName. This option is provided for deleting a directory structure.

Arguments
this& A handle to a directory scan object
name$ The top level directory for the scan. Any path components which are not specified here will be taken from the session path.
attMask& A bit mask which filters the entry types which should be returned by NextL(). The mask works as follows. To match files only, specify KEntryAttNormal&. To match both files and directories, specify KEntryAttDir&. To match directories only, specify KEntryAttDir& OR KEntryAttMatchExclusive&. To match files with a specific attribute, OR the attribute involved with KEntryAttMatchExclusive&. For example, to match read-only files, specify KEntryAttReadOnly& OR KEntryAttMatchExclusive&. See File or directory attributes for a full list of the attributes supported.
sortMask& The order in which the directories are scanned by NextL(). For a list of the sort keys available, see Order of directory entries
scanDirection% The direction of the scan.
Error Handling

If the scan data cannot be created then an error is generated which should be trapped by an ONERR handler.


Constants provided


Scan direction

KDirScanUpTree% Scan upwards from the lowest level directory in the hierarchy to the top level directory
KDirScanDownTree% Scan downwards from the top level directory in the hierarchy to the bottom level directory