Extending Directory()

Download source code: EXTDIR.MEF (8K)

The CAVO20 forum on Compuserve is an excellent venue for discussing issues relating to CA-Visual Objects 2.0. Recently some people in the forum reported that the Directory() function was not returning all the names of the files that it should have. In response to that, I started investigating the possibility of using some of the Windows API functions to provide an alternative. This article explains the solution I came up with, and shows how to include additional information not normally provided by Directory().

There are two main functions in the Windows API that provide the basis for our replacement directory function: FindFirstFile() and FindNextFile().

The FindFirstFile() function accepts two parameters, a PSZ containing the required file specification (including wildcards, if necessary) and a pointer to a block of memory that will be filled with information about the first file matching the specification. FindFirstFile() returns a "search handle", which is a value that is passed to the companion FindNextFile() function. Again, FindNextFile takes a second parameter that is a pointer to a block of memory to be filled with details about the next file that is found.

In VO2, the structure of the memory containing the file details is called _WINWIN32_FIND_DATA, listed below:

On examination of this structure, we find that we not only have the necessary information to derive the values normally returned by Directory(), but there are also additional members that we can make use of such as cFileName, which contains the long filename, ftCreationTime which contains details of when the file was created, and ftLastAccessTime, containing details of when the file was last accessed. And looking deeper into the dwFileAttributes member reveals there are additonal file attribute flags, such as COMPRESSED, OFFLINE and TEMPORARY.

Having found this information in the Windows API, we see that it is possible not only to match the functionality of Directory(), but to extend it as well.

I decided to try to make our new function similar to Directory(), but not exactly the same. I have deliberately left out the disk volume information - in fact that might be a project for another day, since the Windows API function GetVolumeInformation() has additional information not normally provided by Directory().

The skeleton of our new function can be as follows:

This code simply sets up a block of memory to contain the file details (by declaring pFindData IS _WINWIN32_FIND_DATA), and attempts to find the first matching file by calling FindFirstFile(). If that is successful, it adds the information to an array by calling ConvertFindData() (more about that below), and then keeps looking for further files by looping and calling FindNextFile(). As long as further files are found the structure information is again analysed by ConvertFindData(), and the results added to the array.

The ConvertFindData() function takes the _WINWIN32_FIND_DATA structure and converts the information into a format that is more familiar and friendly to VO programmers. Since the Directory() function returns an array for each file found, I thought we would do the same, but extend it to include the additional information we have at hand.

Each piece of information in the structure needs some type of manipulation to get it into our VO style format. Let's start with the filename.

The structure contains both the long version of the filename and the short (8.3) version. The cFilename member contains the long filename, and cAlternateFilename contains the short filename. We can convert both of these into VO strings as shown below:

The size of the file can be calculated from the nFileSizeHigh and nFileSizeLow members:

The time related members, ftLastWriteTime, ftCreationTime, and ftLastAccessTime are actually formatted in Coordinated Universal Time (UTC) format. Windows provides the FileTimeToLocalFileTime() function to convert these into local time, and then FileTimeToSystemTime() to break the time into year, month, day, hour, minute, second, etc. To simplify the process of converting these values, I have come up with the UTC2DateTime() function, which will take a UTC value and return an array containing the corresponding date and time. The code for this function is included below:

With this function, we can easily convert each of the time related members by following the technique listed in these few lines of code:

All that remains is to convert the file attributes, which are stored in a DWORD, into a character string like that provided by directory. This can be achieved by using the following function:

Using all these components, the whole ConvertFindData() function can be written like this:

We just need to have a few extra DEFINEs to extend the array that Directory normally provides:

As written so far, ExtendedDirectory() returns all directory entries. However, Directory() normally does not include System or Hidden files, or Directories. The final thing we need to do is simulate this behaviour.

Directory() allows you to pass a seconds parameter containing the attributes of files to be included in the returned array. This parameter can be a numeric (e.g. FA_DIRECTORY) or a string (e.g. "D")

We can also do this with ExtendedDirectory(). The code below shows how we can convert a string into the corresponding DWORD in ExtendedDirectory()

We can then use this requested attributes to aid in determining if the retrieved file's details should be added to the array by making a change:

And the FileAttributesOK() function can decide if the attributes of the file are suitable:

In this article we have been able to make use of the Windows API to give us a more powerful Directory() function. It highlights the fact that there is additional information in the Windows environment, just waiting to be tapped. And accessing that information from Visual Objects is definitely possible.