Directory file listing utility

• Download demo - 158 KB
• Download source - 24.2 KB

Introduction

I’ve come across countless situations where routinely used utilitarian functions are simply not available, and coders simply have to write and rewrite them many times over. This is my first article in a series of articles which will try to provide a collection of routinely used functions with example applications on how to use them, in the hope that they will be as useful to the many developers out there as it has been to me.

One such function is to obtain a list of all files (their absolute paths) given a directory to start with, with options to search recursively into sub-directories or just to output the files present directly under the given directory.

I’ve found this to be extremely useful in many projects which required going through each file for some reason or the other.

Background

This function was developed many years ago when I stumbled upon a barrage of projects that required reading into every file in a given directory, and also provide progress information in real time, e.g., which file is being currently processed, total number of files, and number of files already processed. Since then, I’ve probably used this function in a few dozen projects.

Using the Code

Follow these simple steps to use the code in your project:

1. Add the files Util.h and Util.cpp into your Visual Studio C++ project (or any other kind of project, I have never used the code on anything other than Visual Studio C++ projects, so any input on using it on other C++ projects is appreciated).
2. Add the line #include “Util.h” in the top section of the *.cpp files you intend to use this function in.
3. Declare a vector of stlStrings: vector<stlString> vecstrFileList;.
4. Call the static function "GetFileList()" with the required parameters.
5. The vector will now have all the file paths found in the directory specified, each element of the vector being a string representing the absolute path of a file. Note that you must explicitly clear the vector before reusing it, unless you want the function to append to the vector. The function will also work on network drive directory paths.
6. Take a look at the "Get file list" button event handler function in the source code to see steps 1 to 5 in action.
7. Check the "Util.cpp" source file, or the code snippet below, for a detailed description of how the function is working internally, it is extensively commented.

void CUtil::GetFileList(const stlString& strTargetDirectory, 
     bool bLookInSubdirectories, vector<stlstring>& vecstrFileList)
{
    // Check whether target directory string is empty
    if(strTargetDirectory.compare(_T("")) == 0)
    {
        return;
    }

    // Remove "\\" if present at the end of the target directory
    // Then make a copy of it and use as the current search directory
    stlString strCurrentDirectory = RemoveDirectoryEnding(strTargetDirectory);

    // This data structure stores information about the file/folder
    // that is found by any of these Win32 API functions:
    // FindFirstFile, FindFirstFileEx, or FindNextFile function
    WIN32_FIND_DATA fdDesktop = {0};

    // Check which character set is being used and allocate array of required type
#ifdef UNICODE
    wchar_t strDesktopPath[_MAX_PATH];
#else
    char strDesktopPath[_MAX_PATH];
#endif

    // Format and copy the current directory to the character array
    // Note the addition of the wildcard *.*, which represents all files
    // 
    // Below is a list of wildcards that you can use
    // * (asterisk)            - represents zero or more characters
    //                        at the current character position
    // ? (question mark)    - represents a single character
    //
    // Modify this function so that the function can take in a search pattern
    // with wildcards and use it in the line below to find for e.g. only *.mpg files
    _stprintf_s(strDesktopPath, _MAX_PATH, _T("%s\\*.*"), strCurrentDirectory.c_str());

    // Finds the first file and populates
    // the WIN32_FIND_DATA data structure with its information
    // The return value is a search handle used in subsequent calls
    // to FindNextFile or FindClose functions
    HANDLE hDesktop = ::FindFirstFile(strDesktopPath, &fdDesktop);    

    // If an invalid handle is returned by FindFirstFile function,
    // something went wrong, so just quit
    if(hDesktop == INVALID_HANDLE_VALUE)
    {
        return;
    }

    // Do this on the first file found and repeat for every next
    // file found until all the required files that match the search pattern are found
    do 
    {
        // Check if a directory was found
        if(fdDesktop.dwFileAttributes & FILE_ATTRIBUTE_DIRECTORY)
        {
            // Reconstruct the directory path
            _stprintf_s(strDesktopPath, _MAX_PATH, _T("%s\\%s"), 
                        strCurrentDirectory.c_str(), fdDesktop.cFileName);
            
            // Get the name of the directory
            stlString strCurrentDirectoryName = GetDirectoryName(strDesktopPath);

            // If its a current (.) or previous (..) directory indicator, just skip it
            if((strCurrentDirectoryName.compare(_T(".")) == 0) || 
               (strCurrentDirectoryName.compare(_T("..")) == 0))
            {
                continue;
            }
            // Other wise this is a sub-directory
            else
            {
                // Check whether function was called
                // to include sub-directories in the search
                if(bLookInSubdirectories)
                {
                    // If sub-directories are to be searched as well, recursively
                    // call the function again,
                    // with the target directory as the sub-directory
                    GetFileList(strDesktopPath, bLookInSubdirectories, vecstrFileList);
                }
            }
        }
        // A file was found
        else
        // if(fdDesktop.dwFileAttributes & FILE_ATTRIBUTE_NORMAL)
        {
            // Reconstruct the file path
            _stprintf_s(strDesktopPath, _MAX_PATH, _T("%s\\%s"), 
                        strCurrentDirectory.c_str(), fdDesktop.cFileName);
            
            // Create a stlString for the file path
            stlString strFilePath = strDesktopPath;
            
            // Add the string to the vector
            vecstrFileList.push_back(strFilePath);
        }
    }
    // Search for the next file that matches the search pattern
    while(::FindNextFile(hDesktop, &fdDesktop) == TRUE);

    // Close the search handle
    ::FindClose(hDesktop);
}

Points of Interest

The code provided here is for unmanaged C++; if you are using managed code or C#, which uses the .NET Framework, you can use the Directory.GetFiles methods; you can read about it here.

While writing this code, I found that, to my annoyance, Microsoft Windows does not have any easy to use unmanaged C++ code to actually do this in a straightforward and simple manner. If you do find this code useful, please leave a comment, it could make my day :-)

History

• V1.0 - Initial release.