fs_main.cpp

/**
 * @file fs_main.cpp
 *
 * @ingroup fs
 *
 * @author Copyright &copy; 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
 * @author Copyright &copy; 2006-2012 Daniel Swanson <danij@dengine.net>
 * @author Copyright &copy; 2006 Jamie Jones <jamie_jones_au@yahoo.com.au>
 * @author Copyright &copy; 1993-1996 by id Software, Inc.
 *
 * @par License
 * GPL: http://www.gnu.org/licenses/gpl.html
 *
 * <small>This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by the
 * Free Software Foundation; either version 2 of the License, or (at your
 * option) any later version. This program is distributed in the hope that it
 * will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
 * of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
 * Public License for more details. You should have received a copy of the GNU
 * General Public License along with this program; if not, write to the Free
 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
 * 02110-1301 USA</small>
 */

#include <cstdlib>
#include <cctype>
#include <ctime>

#include "de_base.h"
#include "de_console.h"
#include "de_filesys.h"

#include "fileid.h"
#include "game.h"
#include "file.h"
#include "lumpindex.h"
#include "fileinfo.h"
#include "lumpfileadaptor.h"
#include "m_misc.h" // for M_FindWhite()
#include "wad.h"
#include "zip.h"

#include <QList>
#include <QtAlgorithms>

#include <de/Log>
#include <de/memory.h>

using namespace de;

D_CMD(Dir);
D_CMD(DumpLump);
D_CMD(ListFiles);
D_CMD(ListLumps);

static FS1* fileSystem;

struct FileInterpreter
{
    resourcetype_t resourceType;
    de::File1* (*interpret)(de::FileHandle& hndl, char const* path, FileInfo const& info);
};

static de::File1* interpretAsZipFile(de::FileHandle& hndl, char const* path, FileInfo const& info)
{
    if(!Zip::recognise(hndl)) return 0;
    LOG_VERBOSE("Interpreted \"") << F_PrettyPath(path) << "\" as a Zip (archive)";
    return new Zip(hndl, path, info);
}

static de::File1* interpretAsWadFile(de::FileHandle& hndl, char const* path, FileInfo const& info)
{
    if(!Wad::recognise(hndl)) return 0;
    LOG_VERBOSE("Interpreted \"") << F_PrettyPath(path) << "\" as a Wad (archive)";
    return new Wad(hndl, path, info);
}

/// @todo Order here should be determined by the resource locator.
static FileInterpreter interpreters[] = {
    { RT_ZIP,  interpretAsZipFile },
    { RT_WAD,  interpretAsWadFile },
    { RT_NONE, NULL }
};

typedef QList<FileId> FileIds;

/**
 * Virtual (file) path => Lump name mapping.
 *
 * @todo We can't presently use a Map or Hash for these. Although the paths are
 *       unique, several of the existing algorithms which match using patterns
 *       assume they are sorted in a quasi load ordering.
 */
typedef QPair<QString, QString> LumpMapping;
typedef QList<LumpMapping> LumpMappings;

/**
 * Virtual file-directory mapping.
 * Maps one (absolute) path in the virtual file system to another.
 *
 * @todo We can't presently use a Map or Hash for these. Although the paths are
 *       unique, several of the existing algorithms which match using patterns
 *       assume they are sorted in a quasi load ordering.
 */
typedef QPair<QString, QString> PathMapping;
typedef QList<PathMapping> PathMappings;

static bool applyPathMapping(ddstring_t* path, PathMapping const& vdm);

struct FS1::Instance
{
    /// Base for indicies in the auxiliary lump index.
    static int const AUXILIARY_BASE = 100000000;

    FS1* self;

    /// @c true= Flag newly opened files as "startup".
    bool loadingForStartup;

    /// List of currently opened files.
    FileList openFiles;

    /// List of all loaded files present in the file system.
    FileList loadedFiles;

    /// Database of unique identifiers for all loaded/opened files.
    FileIds fileIds;

    LumpIndex zipLumpIndex;

    LumpIndex primaryWadLumpIndex;
    LumpIndex auxiliaryWadLumpIndex;
    // @c true = one or more files have been opened using the auxiliary index.
    bool auxiliaryWadLumpIndexInUse;

    // Currently selected lump index.
    LumpIndex* ActiveWadLumpIndex;

    /// Virtual (file) path => Lump name mapping.
    LumpMappings lumpMappings;

    /// Virtual file-directory mapping.
    PathMappings pathMappings;

    Instance(FS1* d) : self(d), loadingForStartup(true),
        openFiles(), loadedFiles(), fileIds(),
        zipLumpIndex(LIF_UNIQUE_PATHS), primaryWadLumpIndex(),
        auxiliaryWadLumpIndex(), auxiliaryWadLumpIndexInUse(false),
        ActiveWadLumpIndex(&primaryWadLumpIndex)
    {}

    ~Instance()
    {
        clearLoadedFiles();
        clearOpenFiles();
        clearLumpIndexes();

        fileIds.clear(); // Should be null-op if bookkeeping is correct.

        pathMappings.clear();
        lumpMappings.clear();
    }

    /// @return  @c true if the FileId associated with @a path was released.
    bool releaseFileId(char const* path)
    {
        if(path && path[0])
        {
            FileId fileId = FileId::fromPath(path);
            FileIds::iterator place = qLowerBound(fileIds.begin(), fileIds.end(), fileId);
            if(place != fileIds.end() && *place == fileId)
            {
#if _DEBUG
                LOG_VERBOSE("Released FileId %s - \"%s\"") << *place << fileId.path();
#endif
                fileIds.erase(place);
                return true;
            }
        }
        return false;
    }

    void clearLoadedFiles(de::LumpIndex* index = 0)
    {
        // Unload in reverse load order.
        for(int i = loadedFiles.size() - 1; i >= 0; i--)
        {
            FileHandle& hndl = *(loadedFiles[i]);
            if(!index || index->catalogues(hndl.file()))
            {
                releaseFileId(Str_Text(hndl.file().path()));
                self->deindex(hndl.file());
                loadedFiles.removeAt(i);
                self->deleteFile(hndl);
            }
        }
    }

    void clearOpenFiles()
    {
        while(!openFiles.empty())
        { self->deleteFile(*openFiles.back()); }
    }

    /**
     * Handles conversion to a logical index that is independent of the lump index currently in use.
     */
    inline lumpnum_t logicalLumpNum(lumpnum_t lumpNum)
    {
        return (lumpNum < 0 ? -1 :
                ActiveWadLumpIndex == &auxiliaryWadLumpIndex? lumpNum += AUXILIARY_BASE : lumpNum);
    }

    void clearLumpIndexes()
    {
        primaryWadLumpIndex.clear();
        auxiliaryWadLumpIndex.clear();
        zipLumpIndex.clear();

        ActiveWadLumpIndex = 0;
    }

    void usePrimaryWadLumpIndex()
    {
        ActiveWadLumpIndex = &primaryWadLumpIndex;
    }

    bool useAuxiliaryWadLumpIndex()
    {
        if(!auxiliaryWadLumpIndexInUse) return false;
        ActiveWadLumpIndex = &auxiliaryWadLumpIndex;
        return true;
    }

    /**
     * Selects which lump index to use, given a logical lump number.
     * The lump number is then translated into range for the selected index.
     * This should be called in all functions that access lumps by logical lump number.
     */
    void selectWadLumpIndex(lumpnum_t& lumpNum)
    {
        if(lumpNum >= AUXILIARY_BASE)
        {
            useAuxiliaryWadLumpIndex();
            lumpNum -= AUXILIARY_BASE;
        }
        else
        {
            usePrimaryWadLumpIndex();
        }
    }

    de::FileHandle* tryOpenLump(char const* path, char const* /*mode*/, size_t /*baseOffset*/,
                                bool allowDuplicate, FileInfo& retInfo)
    {
        DENG_ASSERT(path && path[0]);

        // Convert to an absolute path.
        AutoStr* absSearchPath = AutoStr_FromTextStd(path);
        F_PrependBasePath(absSearchPath, absSearchPath);

        File1 const* found = 0;

        // First check the Zip lump index.
        lumpnum_t lumpNum = zipLumpIndex.indexForPath(Str_Text(absSearchPath));
        if(lumpNum >= 0)
        {
            found = &zipLumpIndex.lump(lumpNum);
        }
        // Nope. Any applicable dir/WAD redirects?
        else if(!lumpMappings.empty())
        {
            // We must have an absolute path - prepend the CWD if necessary.
            Str_Set(absSearchPath, path);
            F_PrependWorkPath(absSearchPath, absSearchPath);

            DENG2_FOR_EACH(i, lumpMappings, LumpMappings::const_iterator)
            {
                LumpMapping const& mapping = *i;
                QByteArray foundPathUtf8 = mapping.first.toUtf8();
                if(qstricmp(foundPathUtf8.constData(), Str_Text(absSearchPath))) continue;

                QByteArray foundLumpNameUtf8 = mapping.second.toUtf8();
                lumpnum_t absoluteLumpNum = self->lumpNumForName(foundLumpNameUtf8.constData());
                if(absoluteLumpNum < 0) continue;

                found = &self->nameIndexForLump(absoluteLumpNum).lump(absoluteLumpNum);
            }
        }

        // Nothing?
        if(!found) return 0;

        // Do not read files twice.
        if(!allowDuplicate && !self->checkFileId(path)) return 0;

        // Get a handle to the lump we intend to open.
        /// @todo The way this buffering works is nonsensical it should not be done here
        ///        but should instead be deferred until the content of the lump is read.
        FileHandle* hndl = FileHandleBuilder::fromFileLump(found->container(), found->info().lumpIdx, false/*dontBuffer*/);

        // Prepare a temporary info descriptor.
        retInfo = found->info();

        return hndl;
    }

    de::FileHandle* tryOpenNativeFile(char const* path, char const* mymode, size_t baseOffset,
                                      bool allowDuplicate, FileInfo& info)
    {
        DENG_ASSERT(path && path[0]);

        // Translate mymode to the C-lib's fopen() mode specifiers.
        char mode[8] = "";
        if(strchr(mymode, 'r'))      strcat(mode, "r");
        else if(strchr(mymode, 'w')) strcat(mode, "w");
        if(strchr(mymode, 'b'))      strcat(mode, "b");
        else if(strchr(mymode, 't')) strcat(mode, "t");

        AutoStr* nativePath = AutoStr_FromTextStd(path);
        F_ExpandBasePath(nativePath, nativePath);
        // We must have an absolute path - prepend the CWD if necessary.
        F_PrependWorkPath(nativePath, nativePath);
        F_ToNativeSlashes(nativePath, nativePath);

        AutoStr* foundPath = 0;

        // First try a real native file at this absolute path.
        FILE* nativeFile = fopen(Str_Text(nativePath), mode);
        if(nativeFile)
        {
            foundPath = nativePath;
        }
        // Nope. Any applicable virtual directory mappings?
        else if(!pathMappings.empty())
        {
            AutoStr* mapped = AutoStr_NewStd();
            DENG2_FOR_EACH(i, pathMappings, PathMappings::const_iterator)
            {
                Str_Set(mapped, path);
                if(!applyPathMapping(mapped, *i)) continue;
                // The mapping was successful.

                F_ToNativeSlashes(nativePath, mapped);
                nativeFile = fopen(Str_Text(nativePath), mode);
                if(nativeFile)
                {
                    LOG_DEBUG("FS::tryOpenNativeFile: \"%s\" opened as %s.")
                        << F_PrettyPath(Str_Text(mapped)) << path;
                    foundPath = mapped;
                    break;
                }
            }
        }

        // Nothing?
        if(!nativeFile) return 0;

        // Do not read files twice.
        if(!allowDuplicate && !self->checkFileId(Str_Text(foundPath)))
        {
            fclose(nativeFile);
            return 0;
        }

        // Acquire a handle on the file we intend to open.
        FileHandle* hndl = FileHandleBuilder::fromNativeFile(*nativeFile, baseOffset);

        // Prepare the temporary info descriptor.
        info = FileInfo(F_GetLastModified(Str_Text(foundPath)));

        return hndl;
    }

    de::File1* tryOpenFile(char const* path, char const* mode, size_t baseOffset,
                           bool allowDuplicate)
    {
        if(!path || !path[0]) return 0;
        if(!mode) mode = "";

        bool const reqNativeFile = !!strchr(mode, 'f');

        // Make it a full path.
        AutoStr* searchPath = AutoStr_FromTextStd(path);
        F_FixSlashes(searchPath, searchPath);
        F_ExpandBasePath(searchPath, searchPath);

        DEBUG_VERBOSE2_Message(("FS1::tryOpenFile: trying to open %s\n", Str_Text(searchPath)));

        FileHandle* hndl = 0;
        FileInfo info; // The temporary info descriptor.

        // First check for lumps?
        if(!reqNativeFile)
        {
            hndl = tryOpenLump(Str_Text(searchPath), mode, baseOffset, allowDuplicate, info);
        }

        // Not found? - try a native file.
        if(!hndl)
        {
            hndl = tryOpenNativeFile(Str_Text(searchPath), mode, baseOffset, allowDuplicate, info);
        }

        // Nothing?
        if(!hndl) return 0;

        // Search path is used here rather than found path as the latter may have
        // been mapped to another location. We want the file to be attributed with
        // the path it is to be known by throughout the virtual file system.

        File1& file = self->interpret(*hndl, Str_Text(searchPath), info);

        if(loadingForStartup)
        {
            file.setStartup(true);
        }

        return &file;
    }
};

FS1::FS1()
{
    d = new Instance(this);
    FileHandleBuilder::init();
}

FS1::~FS1()
{
    closeAuxiliary();
    delete d;

    FileHandleBuilder::shutdown();
}

void FS1::consoleRegister()
{
    C_CMD("dir", "", Dir);
    C_CMD("ls", "", Dir); // Alias
    C_CMD("dir", "s*", Dir);
    C_CMD("ls", "s*", Dir); // Alias

    C_CMD("dump", "s", DumpLump);
    C_CMD("listfiles", "", ListFiles);
    C_CMD("listlumps", "", ListLumps);
}

/**
 * @note Performance is O(n).
 * @return @c iterator pointing to list->end() if not found.
 */
static FS1::FileList::iterator findListFileByPath(FS1::FileList& list, char const* path_)
{
    if(list.empty()) return list.end();
    if(!path_ || !path_[0]) return list.end();

    // Transform the path into one we can process.
    AutoStr* path = AutoStr_FromTextStd(path_);
    F_FixSlashes(path, path);

    // Perform the search.
    FS1::FileList::iterator i;
    for(i = list.begin(); i != list.end(); ++i)
    {
        de::File1& file = (*i)->file();
        if(!Str_CompareIgnoreCase(file.path(), Str_Text(path)))
        {
            break; // This is the node we are looking for.
        }
    }
    return i;
}

void FS1::index(de::File1& file)
{
    // Publish lumps to an index?
    if(Zip* zip = dynamic_cast<Zip*>(&file))
    {
        if(zip->empty()) return;

        LumpIndex& index = d->zipLumpIndex;
        // Insert the lumps into their rightful places in the index.
        index.catalogLumps(*zip, 0, zip->lumpCount());
        return;
    }
    if(Wad* wad = dynamic_cast<Wad*>(&file))
    {
        if(wad->empty()) return;

        LumpIndex& index = *d->ActiveWadLumpIndex;
        // Insert the lumps into their rightful places in the index.
        index.catalogLumps(*wad, 0, wad->lumpCount());
        return;
    }
    if(LumpFileAdaptor* lump = dynamic_cast<LumpFileAdaptor*>(&file))
    {
        LumpIndex& index = *d->ActiveWadLumpIndex;
        // This *is* the lump, so insert ourself as a lump of our container in the index.
        index.catalogLumps(lump->container(), lump->info().lumpIdx, lump->lumpCount());
        return;
    }
}

void FS1::deindex(de::File1& file)
{
    d->zipLumpIndex.pruneByFile(file);
    d->primaryWadLumpIndex.pruneByFile(file);
    if(d->auxiliaryWadLumpIndexInUse)
        d->auxiliaryWadLumpIndex.pruneByFile(file);
}

bool FS1::unloadFile(char const* path, bool permitRequired, bool quiet)
{
    // Convert to an absolute path.
    AutoStr* absolutePath = AutoStr_FromTextStd(path);
    F_PrependBasePath(absolutePath, absolutePath);

    FileList::iterator found = findListFileByPath(d->loadedFiles, Str_Text(absolutePath));
    if(found == d->loadedFiles.end()) return false;

    // Do not attempt to unload a resource required by the current game.
    if(!permitRequired)
    {
        bool isRequired = false;

        if(AbstractResource* const* records = reinterpret_cast<de::Game*>(App_CurrentGame())->resources(RC_PACKAGE, 0))
        {
            // Is this resource from a container?
            lumpnum_t lumpNum = d->zipLumpIndex.indexForPath(Str_Text(absolutePath));
            if(lumpNum >= 0)
            {
                // Yes; use the container's path instead.
                Str_Copy(absolutePath, d->zipLumpIndex.lump(lumpNum).container().path());
            }

            for(AbstractResource* const* i = records; *i; i++)
            {
                AbstractResource* record = *i;
                if(AbstractResource_ResourceFlags(record) & RF_STARTUP)
                {
                    ddstring_t const* resolvedPath = AbstractResource_ResolvedPath(record, true);
                    if(resolvedPath && !Str_CompareIgnoreCase(resolvedPath, Str_Text(absolutePath)))
                    {
                        isRequired = true;
                        break;
                    }
                }
            }
        }

        if(isRequired)
        {
            if(!quiet)
            {
                Con_Message("\"%s\" is required by the current game.\n"
                            "Required game files cannot be unloaded in isolation.\n",
                            F_PrettyPath(Str_Text(absolutePath)));
            }
            return false;
        }
    }

    if(!quiet && verbose >= 1)
    {
        Con_Message("Unloading \"%s\"...\n", F_PrettyPath(Str_Text(absolutePath)));
    }

    FileHandle& hndl = *(*found);
    d->releaseFileId(Str_Text(hndl.file().path()));
    deindex(hndl.file());
    d->loadedFiles.erase(found);
    deleteFile(hndl);
    return true;
}

#if _DEBUG
static void printFileIds(FileIds const& fileIds)
{
    uint idx = 0;
    DENG2_FOR_EACH(i, fileIds, FileIds::const_iterator)
    {
        LOG_MSG("  %u - %s : \"%s\"") << idx << *i << i->path();
        ++idx;
    }
}
#endif

#if _DEBUG
static void printFileList(FS1::FileList& list)
{
    uint idx = 0;
    DENG2_FOR_EACH(i, list, FS1::FileList::const_iterator)
    {
        de::FileHandle* hndl = *i;
        de::File1& file = hndl->file();
        FileId fileId = FileId::fromPath(Str_Text(file.path()));
        LOG_MSG(" %c%d: %s - \"%s\" (handle: %p)")
            << (file.hasStartup()? '*' : ' ') << idx
            << fileId << fileId.path() << (void*)&hndl;
        ++idx;
    }
}
#endif

FS1& FS1::unloadAllNonStartupFiles(int* retNumUnloaded)
{
#if _DEBUG
    // List all open files with their identifiers.
    if(verbose)
    {
        LOG_MSG("Open files at reset:");
        printFileList(d->openFiles);
        LOG_MSG("End\n");
    }
#endif

    // Perform non-startup file unloading (in reverse load order).
    int numUnloaded = 0;
    for(int i = d->loadedFiles.size() - 1; i >= 0; i--)
    {
        FileHandle& hndl = *(d->loadedFiles[i]);
        File1& file = hndl.file();
        if(file.hasStartup()) continue;

        if(unloadFile(Str_Text(file.path()), true/*allow unloading game resources*/, true/*quiet please*/))
        {
            numUnloaded += 1;
        }
    }

#if _DEBUG
    // Sanity check: look for orphaned identifiers.
    if(!d->fileIds.empty())
    {
        LOG_MSG("Warning: Orphan FileIds:");
        printFileIds(d->fileIds);
    }
#endif

    if(retNumUnloaded) *retNumUnloaded = numUnloaded;
    return *this;
}

bool FS1::checkFileId(char const* path)
{
    DENG_ASSERT(path);
    if(!accessFile(path)) return false;

    // Calculate the identifier.
    FileId fileId = FileId::fromPath(path);
    FileIds::iterator place = qLowerBound(d->fileIds.begin(), d->fileIds.end(), fileId);
    if(place != d->fileIds.end() && *place == fileId) return false;

#if _DEBUG
    LOG_VERBOSE("Added FileId %s - \"%s\"") << fileId << fileId.path();
#endif

    d->fileIds.insert(place, fileId);
    return true;
}

void FS1::resetFileIds()
{
    d->fileIds.clear();
}

void FS1::endStartup()
{
    d->loadingForStartup = false;
    d->usePrimaryWadLumpIndex();
}

LumpIndex const& FS1::nameIndex() const
{
    DENG_ASSERT(d->ActiveWadLumpIndex);
    return *d->ActiveWadLumpIndex;
}

LumpIndex const& FS1::nameIndexForLump(lumpnum_t& absoluteLumpNum) const
{
    if(absoluteLumpNum >= Instance::AUXILIARY_BASE)
    {
        absoluteLumpNum -= Instance::AUXILIARY_BASE;
        return d->auxiliaryWadLumpIndex;
    }
    return d->primaryWadLumpIndex;
}

typedef enum lumpsizecondition_e {
    LSCOND_NONE,
    LSCOND_EQUAL,
    LSCOND_GREATER_OR_EQUAL,
    LSCOND_LESS_OR_EQUAL
} lumpsizecondition_t;

/**
 * Modifies the name so that the size condition is removed.
 */
static void checkSizeConditionInName(ddstring_t* name, lumpsizecondition_t* pCond, size_t* pSize)
{
    DENG_ASSERT(pCond != 0);
    DENG_ASSERT(pSize != 0);

    *pCond = LSCOND_NONE;
    *pSize = 0;

    int i, argPos = 0;
    int len = Str_Length(name);
    char const* txt = Str_Text(name);
    for(i = 0; i < len - 2; ++i, ++txt)
    {
        if(!strncmp(txt, "==", 2))
        {
            *pCond = LSCOND_EQUAL;
            argPos = i + 2;
            break;
        }
        if(!strncmp(txt, ">=", 2))
        {
            *pCond = LSCOND_GREATER_OR_EQUAL;
            argPos = i + 2;
            break;
        }
        if(!strncmp(txt, "<=", 2))
        {
            *pCond = LSCOND_LESS_OR_EQUAL;
            argPos = i + 2;
            break;
        }
    }
    if(!argPos) return;

    // Get the argument.
    *pSize = strtoul(txt + 2, NULL, 10);

    // Remove it from the name.
    Str_Truncate(name, i);
}

lumpnum_t FS1::lumpNumForName(char const* name, bool silent)
{
    lumpnum_t lumpNum = -1;

    if(name && name[0])
    {
        lumpsizecondition_t sizeCond;
        size_t lumpSize = 0, refSize;
        ddstring_t searchPath;

        Str_InitStd(&searchPath); Str_Set(&searchPath, name);

        // The name may contain a size condition (==, >=, <=).
        checkSizeConditionInName(&searchPath, &sizeCond, &refSize);

        // Append a .lmp extension if none is specified.
        if(!F_FindFileExtension(name))
        {
            Str_Append(&searchPath, ".lmp");
        }

        // We have to check both the primary and auxiliary lump indexes
        // because we've only got a name and don't know where it is located.
        // Start with the auxiliary lumps because they have precedence.
        if(d->useAuxiliaryWadLumpIndex())
        {
            lumpNum = d->ActiveWadLumpIndex->indexForPath(Str_Text(&searchPath));

            if(lumpNum >= 0 && sizeCond != LSCOND_NONE)
            {
                // Get the size as well for the condition check.
                lumpSize = d->ActiveWadLumpIndex->lump(lumpNum).info().size;
            }
        }

        // Found it yet?
        if(lumpNum < 0)
        {
            d->usePrimaryWadLumpIndex();
            lumpNum = d->ActiveWadLumpIndex->indexForPath(Str_Text(&searchPath));

            if(lumpNum >= 0 && sizeCond != LSCOND_NONE)
            {
                // Get the size as well for the condition check.
                lumpSize = d->ActiveWadLumpIndex->lump(lumpNum).info().size;
            }
        }

        // Check the condition.
        switch(sizeCond)
        {
        case LSCOND_EQUAL:
            if(lumpSize != refSize) lumpNum = -1;
            break;

        case LSCOND_GREATER_OR_EQUAL:
            if(lumpSize < refSize) lumpNum = -1;
            break;

        case LSCOND_LESS_OR_EQUAL:
            if(lumpSize > refSize) lumpNum = -1;
            break;

        default:
            break;
        }

        // If still not found, warn the user.
        if(!silent && lumpNum < 0)
        {
            if(sizeCond == LSCOND_NONE)
            {
                Con_Message("Warning: FS1::lumpNumForName: Lump \"%s\" not found.\n", name);
            }
            else
            {
                Con_Message("Warning: FS1::lumpNumForName: Lump \"%s\" with size%s%i not found.\n",
                            Str_Text(&searchPath), sizeCond==LSCOND_EQUAL? "==" :
                            sizeCond==LSCOND_GREATER_OR_EQUAL? ">=" : "<=", (int)refSize);
            }
        }

        Str_Free(&searchPath);
    }
    else if(!silent)
    {
        Con_Message("Warning: FS1::lumpNumForName: Empty name, returning invalid lumpnum.\n");
    }
    return d->logicalLumpNum(lumpNum);
}

lumpnum_t FS1::openAuxiliary(char const* filePath, size_t baseOffset)
{
    /// @todo Allow opening Zip files too.
    File1* file = d->tryOpenFile(filePath, "rb", baseOffset, true /*allow duplicates*/);
    if(Wad* wad = dynamic_cast<Wad*>(file))
    {
        if(d->auxiliaryWadLumpIndexInUse)
        {
            closeAuxiliary();
        }
        d->ActiveWadLumpIndex = &d->auxiliaryWadLumpIndex;
        d->auxiliaryWadLumpIndexInUse = true;

        index(*wad);

        // Add a handle to the open files list.
        FileHandle* openFilesHndl = FileHandleBuilder::fromFile(*wad);
        d->openFiles.push_back(openFilesHndl); openFilesHndl->setList(reinterpret_cast<struct filelist_s*>(&d->openFiles));

        // Add a handle to the loaded files list.
        FileHandle* loadedFilesHndl = FileHandleBuilder::dup(*openFilesHndl);
        d->loadedFiles.push_back(loadedFilesHndl); loadedFilesHndl->setList(reinterpret_cast<struct filelist_s*>(&d->loadedFiles));

        return Instance::AUXILIARY_BASE;
    }

    delete file;
    return -1;
}

void FS1::closeAuxiliary()
{
    if(d->useAuxiliaryWadLumpIndex())
    {
        d->clearLoadedFiles(&d->auxiliaryWadLumpIndex);
        d->auxiliaryWadLumpIndexInUse = false;
    }
    d->usePrimaryWadLumpIndex();
}

void FS1::releaseFile(de::File1& file)
{
    for(int i = d->openFiles.size() - 1; i >= 0; i--)
    {
        FileHandle& hndl = *(d->openFiles[i]);
        if(&hndl.file() == &file)
        {
            d->openFiles.removeAt(i);
        }
    }
}

void FS1::closeFile(de::FileHandle& hndl)
{
    hndl.close();
}

void FS1::deleteFile(de::FileHandle& hndl)
{
    closeFile(hndl);
    delete &hndl.file();
    delete &hndl;
}

/// @return @c NULL= Not found.
static Wad* findFirstWadFile(FS1::FileList& list, bool custom)
{
    if(list.empty()) return 0;
    DENG2_FOR_EACH(i, list, FS1::FileList::iterator)
    {
        de::File1& file = (*i)->file();
        if(custom != file.hasCustom()) continue;

        Wad* wad = dynamic_cast<Wad*>(&file);
        if(wad) return wad;
    }
    return 0;
}

uint FS1::loadedFilesCRC()
{
    /**
     * We define the CRC as that of the lump directory of the first loaded IWAD.
     * @todo Really kludgy...
     */
    Wad* iwad = findFirstWadFile(d->loadedFiles, false/*not-custom*/);
    if(!iwad) return 0;
    return iwad->calculateCRC();
}

int FS1::findAll(FS1::FileList& found) const
{
    int numFound = 0;
    DENG2_FOR_EACH(i, d->loadedFiles, FS1::FileList::const_iterator)
    {
        found.push_back(*i);
        numFound += 1;
    }
    return numFound;
}

int FS1::findAll(bool (*predicate)(de::FileHandle* hndl, void* parameters), void* parameters,
                 FS1::FileList& found) const
{
    int numFound = 0;
    DENG2_FOR_EACH(i, d->loadedFiles, FS1::FileList::const_iterator)
    {
        // Interested in this file?
        if(predicate && !predicate(*i, parameters)) continue; // Nope.

        found.push_back(*i);
        numFound += 1;
    }
    return numFound;
}

int FS1::findAllPaths(char const* rawSearchPattern, int flags, FS1::PathList& found)
{
    int const numFoundSoFar = found.count();

    // First normalize the raw search pattern into one we can process.
    AutoStr* searchPattern = AutoStr_NewStd();
    Str_Set(searchPattern, rawSearchPattern);
    Str_Strip(searchPattern);
    F_FixSlashes(searchPattern, searchPattern);
    F_ExpandBasePath(searchPattern, searchPattern);

    // An absolute path is required so resolve relative to the base path.
    // if not already absolute.
    F_PrependBasePath(searchPattern, searchPattern);

    PathMap patternMap;
    PathMap_Initialize(&patternMap, PathDirectory::hashPathFragment, Str_Text(searchPattern));

    /*
     * Check the Zip directory.
     */
    DENG2_FOR_EACH(i, d->zipLumpIndex.lumps(), LumpIndex::Lumps::const_iterator)
    {
        File1 const& lump = **i;
        PathDirectoryNode const& node = lump.container().lumpDirectoryNode(lump.info().lumpIdx);

        AutoStr* filePath = 0;
        bool patternMatched;
        if(!(flags & SPF_NO_DESCEND))
        {
            filePath       = lump.container().composeLumpPath(lump.info().lumpIdx);
            patternMatched = F_MatchFileName(Str_Text(filePath), Str_Text(searchPattern));
        }
        else
        {
            patternMatched = node.matchDirectory(PCF_MATCH_FULL, &patternMap);
            if(patternMatched)
            {
                filePath   = lump.container().composeLumpPath(lump.info().lumpIdx);
            }
        }

        if(!patternMatched) continue;

        found.push_back(PathListItem(Str_Text(filePath), node.type() == PT_BRANCH? A_SUBDIR : 0));
    }

    PathMap_Destroy(&patternMap);

    /*
     * Check the dir/WAD direcs.
     */
    if(!d->lumpMappings.empty())
    {
        DENG2_FOR_EACH(i, d->lumpMappings, LumpMappings::const_iterator)
        {
            if(!F_MatchFileName(i->first.toUtf8().constData(), Str_Text(searchPattern))) continue;

            found.push_back(PathListItem(i->first, 0 /*only filepaths (i.e., leaves) can be mapped to lumps*/));
        }

        /// @todo Shouldn't these be sorted? -ds
    }

    /*
     * Check native paths.
     */
    // Extract the directory path.
    AutoStr* searchDirectory = AutoStr_NewStd();
    F_FileDir(searchDirectory, searchPattern);

    if(!Str_IsEmpty(searchDirectory))
    {
        PathList nativePaths;
        AutoStr* wildPath = AutoStr_NewStd();
        finddata_t fd;

        for(int i = -1; i < (int)d->pathMappings.count(); ++i)
        {
            if(i == -1)
            {
                Str_Clear(wildPath);
                Str_Appendf(wildPath, "%s*", Str_Text(searchDirectory));
            }
            else
            {
                // Possible mapping?
                Str_Copy(wildPath, searchDirectory);
                if(!applyPathMapping(wildPath, d->pathMappings[i])) continue;

                Str_AppendChar(wildPath, '*');
            }

            if(!myfindfirst(Str_Text(wildPath), &fd))
            {
                // First path found.
                do
                {
                    // Ignore relative directory symbolics.
                    if(Str_Compare(&fd.name, ".") && Str_Compare(&fd.name, ".."))
                    {
                        QString foundPath = QString("%1%2").arg(Str_Text(searchDirectory)).arg(Str_Text(&fd.name));
                        if(!F_MatchFileName(foundPath.toUtf8().constData(), Str_Text(searchPattern))) continue;

                        nativePaths.push_back(PathListItem(foundPath, fd.attrib));
                    }
                } while(!myfindnext(&fd));
            }
            myfindend(&fd);
        }

        // Sort the native paths.
        qSort(nativePaths.begin(), nativePaths.end());

        // Add the native paths to the found results.
        found.append(nativePaths);
    }

    return found.count() - numFoundSoFar;
}

de::File1& FS1::interpret(de::FileHandle& hndl, char const* path, FileInfo const& info)
{
    DENG_ASSERT(path && path[0]);

    de::File1* interpretedFile = 0;

    // Firstly try interpreter(s) for guessed resource types.
    resourcetype_t resTypeGuess = F_GuessResourceTypeByName(path);
    if(resTypeGuess != RT_NONE)
    {
        for(FileInterpreter* intper = interpreters; intper->interpret; ++intper)
        {
            // Not applicable for this resource type?
            if(intper->resourceType != resTypeGuess) continue;

            interpretedFile = intper->interpret(hndl, path, info);
            if(interpretedFile) break;
        }
    }

    // If not yet interpreted - try each recognisable format in order.
    if(!interpretedFile)
    {
        for(FileInterpreter* intper = interpreters; intper->interpret; ++intper)
        {
            // Already tried this?
            if(resTypeGuess && intper->resourceType == resTypeGuess) continue;

            interpretedFile = intper->interpret(hndl, path, info);
            if(interpretedFile) break;
        }
    }

    // Still not interpreted?
    if(!interpretedFile)
    {
        // Use a generic file - LumpFileAdaptor for contained lumps else File.
        if(hndl.hasFile() && hndl.file().isContained())
        {
            interpretedFile = new LumpFileAdaptor(hndl, path, info, &hndl.file().container());
        }
        else
        {
            interpretedFile = new File1(path, hndl, info);
        }
    }

    DENG_ASSERT(interpretedFile);
    return *interpretedFile;
}

de::FileHandle& FS1::openFile(char const* path, char const* mode, size_t baseOffset, bool allowDuplicate)
{
#if _DEBUG
    DENG_ASSERT(path && mode);
    for(uint i = 0; mode[i]; ++i)
    {
        if(mode[i] != 'r' && mode[i] != 't' && mode[i] != 'b' && mode[i] != 'f')
            Con_Error("FS1::openFile: Unsupported file open-op in mode string %s for path \"%s\"\n", mode, path);
    }
#endif

    File1* file = d->tryOpenFile(path, mode, baseOffset, allowDuplicate);
    if(!file) throw NotFoundError("FS1::openFile", "No files found matching '" + QString(path) + "'");

    // Add a handle to the opened files list.
    FileHandle& openFilesHndl = *FileHandleBuilder::fromFile(*file);
    d->openFiles.push_back(&openFilesHndl); openFilesHndl.setList(reinterpret_cast<struct filelist_s*>(&d->openFiles));
    return openFilesHndl;
}

de::FileHandle& FS1::openLump(de::File1& lump)
{
    LumpFileAdaptor* adapt = new LumpFileAdaptor(*FileHandleBuilder::fromFileLump(lump.container(), lump.info().lumpIdx, false),
                                                 Str_Text(lump.container().composeLumpPath(lump.info().lumpIdx)),
                                                 lump.info(), &lump.container());
    DENG_ASSERT(adapt);

    // Add a handle to the opened files list.
    FileHandle& openFilesHndl = *FileHandleBuilder::fromFile(*adapt);
    d->openFiles.push_back(&openFilesHndl); openFilesHndl.setList(reinterpret_cast<struct filelist_s*>(&d->openFiles));
    return openFilesHndl;
}

bool FS1::accessFile(char const* path)
{
    de::File1* file = d->tryOpenFile(path, "rb", 0, true /* allow duplicates */);
    if(!file) return false;
    delete file;
    return true;
}

de::File1* FS1::addFile(char const* path, size_t baseOffset)
{
    try
    {
        FileHandle& hndl = openFile(path, "rb", baseOffset, false /* no duplicates */);

        // Load the file (a.k.a., index it).
        File1& file = hndl.file();
        VERBOSE( Con_Message("Loading \"%s\"...\n", F_PrettyPath(Str_Text(file.path()))) )

        index(file);

        // Add a handle to the loaded files list.
        FileHandle* loadedFilesHndl = FileHandleBuilder::dup(hndl);
        d->loadedFiles.push_back(loadedFilesHndl); loadedFilesHndl->setList(reinterpret_cast<struct filelist_s*>(&d->loadedFiles));

        return &file;
    }
    catch(NotFoundError const&)
    {
        if(accessFile(path))
        {
            // Must already be loaded.
            Con_Message("\"%s\" already loaded.\n", F_PrettyPath(path));
        }
    }
    return 0;
}

int FS1::addFiles(char const* const* paths, int num)
{
    if(!paths) return 0;

    int addedFileCount = 0;
    for(int i = 0; i < num; ++i)
    {
        if(addFile(paths[i]))
        {
            VERBOSE2( Con_Message("Done loading %s\n", F_PrettyPath(paths[i])) )
            addedFileCount += 1;
        }
        else
        {
            Con_Message("Warning: Errors occured while loading %s\n", paths[i]);
        }
    }

    // A changed file list may alter the main lump directory.
    if(addedFileCount)
    {
        DD_UpdateEngineState();
    }

    return addedFileCount;
}

bool FS1::removeFile(char const* path, bool permitRequired)
{
    bool didUnload = unloadFile(path, permitRequired);
    if(didUnload)
    {
        DD_UpdateEngineState();
    }
    return didUnload;
}

int FS1::removeFiles(char const* const* filenames, int num, bool permitRequired)
{
    if(!filenames) return 0;

    int removedFileCount = 0;
    for(int i = 0; i < num; ++i)
    {
        if(unloadFile(filenames[i], permitRequired))
        {
            VERBOSE2( Con_Message("Done unloading %s\n", F_PrettyPath(filenames[i])) )
            removedFileCount += 1;
        }
    }

    // A changed file list may alter the main lump directory.
    if(removedFileCount)
    {
        DD_UpdateEngineState();
    }
    return removedFileCount;
}

void FS1::mapPathToLump(char const* symbolicPath, char const* lumpName)
{
    if(!symbolicPath || !symbolicPath[0] || !lumpName || !lumpName[0]) return;

    // Convert the symbolic path into a real path.
    AutoStr* path = AutoStr_FromTextStd(symbolicPath);
    F_ResolveSymbolicPath(path, path);

    // Since the path might be relative, let's explicitly make the path absolute.
    char* full = _fullpath(0, Str_Text(path), 0);
    de::String fullPath = de::String::fromNativePath(full);
    free(full);

    // Have already mapped this path?
    LumpMappings::iterator found = d->lumpMappings.begin();
    for(; found != d->lumpMappings.end(); ++found)
    {
        LumpMapping const& ldm = *found;
        if(!ldm.first.compare(fullPath, Qt::CaseInsensitive))
            break;
    }

    LumpMapping* ldm;
    if(found == d->lumpMappings.end())
    {
        // No. Acquire another mapping.
        d->lumpMappings.push_back(LumpMapping(fullPath, lumpName));
        ldm = &d->lumpMappings.back();
    }
    else
    {
        // Remap to another lump.
        ldm = &*found;
        ldm->second = lumpName;
    }

    QByteArray pathUtf8 = ldm->first.toUtf8();
    LOG_VERBOSE("Path \"%s\" now mapped to lump \"%s\"") << F_PrettyPath(pathUtf8.constData()) << ldm->second;
}

FS1& FS1::clearPathLumpMappings()
{
    d->lumpMappings.clear();
    return *this;
}

/// @return  @c true iff the mapping matched the path.
static bool applyPathMapping(ddstring_t* path, PathMapping const& pm)
{
    if(!path) return false;
    QByteArray destUtf8 = pm.first.toUtf8();
    AutoStr* dest = AutoStr_FromTextStd(destUtf8.constData());
    if(qstrnicmp(Str_Text(path), Str_Text(dest), Str_Length(dest))) return false;

    // Replace the beginning with the source path.
    QByteArray sourceUtf8 = pm.second.toUtf8();
    AutoStr* temp = AutoStr_FromTextStd(sourceUtf8.constData());
    Str_PartAppend(temp, Str_Text(path), pm.first.length(), Str_Length(path) - pm.first.length());
    Str_Copy(path, temp);
    return true;
}

void FS1::mapPath(char const* source, char const* destination)
{
    if(!source || !source[0] || !destination || !destination[0]) return;

    AutoStr* dest = AutoStr_FromTextStd(destination);
    Str_Strip(dest);
    F_FixSlashes(dest, dest);
    F_ExpandBasePath(dest, dest);
    F_PrependWorkPath(dest, dest);
    F_AppendMissingSlash(dest);

    AutoStr* src = AutoStr_FromTextStd(source);
    Str_Strip(src);
    F_FixSlashes(src, src);
    F_ExpandBasePath(src, src);
    F_PrependWorkPath(src, src);
    F_AppendMissingSlash(src);

    // Have already mapped this source path?
    PathMappings::iterator found = d->pathMappings.begin();
    for(; found != d->pathMappings.end(); ++found)
    {
        PathMapping const& pm = *found;
        if(!pm.second.compare(Str_Text(src), Qt::CaseInsensitive))
            break;
    }

    PathMapping* pm;
    if(found == d->pathMappings.end())
    {
        // No. Acquire another mapping.
        d->pathMappings.push_back(PathMapping(Str_Text(dest), Str_Text(src)));
        pm = &d->pathMappings.back();
    }
    else
    {
        // Remap to another destination.
        pm = &*found;
        pm->first = Str_Text(dest);
    }

    QByteArray sourceUtf8 = pm->second.toUtf8();
    QByteArray destUtf8   = pm->first.toUtf8();
    LOG_VERBOSE("Path \"%s\" now mapped to \"%s\"")
            << F_PrettyPath(sourceUtf8.constData()) << F_PrettyPath(destUtf8.constData());
}

FS1& FS1::clearPathMappings()
{
    d->pathMappings.clear();
    return *this;
}

void FS1::printDirectory(ddstring_t const* path)
{
    AutoStr* searchPattern = AutoStr_FromTextStd(Str_Text(path));

    Str_Strip(searchPattern);
    F_FixSlashes(searchPattern, searchPattern);
    // Ensure it ends in a directory separator character.
    F_AppendMissingSlash(searchPattern);
    if(!F_ExpandBasePath(searchPattern, searchPattern))
        F_PrependBasePath(searchPattern, searchPattern);

    Con_Printf("Directory: %s\n", F_PrettyPath(Str_Text(searchPattern)));

    // Make the pattern.
    Str_AppendChar(searchPattern, '*');

    PathList found;
    if(findAllPaths(Str_Text(searchPattern), 0, found))
    {
        qSort(found.begin(), found.end());

        DENG2_FOR_EACH(i, found, PathList::const_iterator)
        {
            QByteArray foundPath = i->path.toUtf8();
            bool const makePretty = CPP_BOOL( F_IsRelativeToBase(foundPath, ddBasePath) );

            Con_Printf("  %s\n", makePretty? F_PrettyPath(foundPath.constData()) : foundPath.constData());
        }
    }
}

/// Print contents of directories as Doomsday sees them.
D_CMD(Dir)
{
    DENG_UNUSED(src);

    ddstring_t path; Str_InitStd(&path);
    if(argc > 1)
    {
        for(int i = 1; i < argc; ++i)
        {
            Str_Set(&path, argv[i]);
            App_FileSystem()->printDirectory(&path);
        }
    }
    else
    {
        Str_Set(&path, "/");
        App_FileSystem()->printDirectory(&path);
    }
    Str_Free(&path);
    return true;
}

/// Dump a copy of a virtual file to the runtime directory.
D_CMD(DumpLump)
{
    DENG_UNUSED(src);
    DENG_UNUSED(argc);

    if(fileSystem)
    {
        lumpnum_t absoluteLumpNum = App_FileSystem()->lumpNumForName(argv[1]);
        if(absoluteLumpNum >= 0)
        {
            return F_DumpLump(absoluteLumpNum);
        }
        Con_Printf("No such lump.\n");
        return false;
    }
    Con_Printf("WAD module is not presently initialized.\n");
    return false;
}

/// List virtual files inside containers.
D_CMD(ListLumps)
{
    DENG_UNUSED(src); DENG_UNUSED(argc); DENG_UNUSED(argv);

    if(fileSystem)
    {
        LumpIndex::print(App_FileSystem()->nameIndex());
        return true;
    }
    Con_Printf("WAD module is not presently initialized.\n");
    return false;
}

/// List presently loaded files in original load order.
D_CMD(ListFiles)
{
    DENG_UNUSED(src); DENG_UNUSED(argc); DENG_UNUSED(argv);

    Con_Printf("Loaded Files (in load order):\n");

    size_t totalFiles = 0, totalPackages = 0;
    if(fileSystem)
    {
        FS1::FileList foundFiles;
        int fileCount = App_FileSystem()->findAll(foundFiles);
        if(!fileCount) return true;

        DENG2_FOR_EACH(i, foundFiles, FS1::FileList::const_iterator)
        {
            de::File1& file = (*i)->file();
            uint crc = 0;

            int fileCount = file.lumpCount();
            if(de::Wad* wad = dynamic_cast<de::Wad*>(&file))
            {
                crc = (!file.hasCustom()? wad->calculateCRC() : 0);
            }

            Con_Printf("\"%s\" (%i %s%s)", F_PrettyPath(Str_Text(file.path())),
                       fileCount, fileCount != 1 ? "files" : "file",
                       (file.hasStartup()? ", startup" : ""));
            if(0 != crc)
                Con_Printf(" [%08x]", crc);
            Con_Printf("\n");

            totalFiles += size_t(fileCount);
            ++totalPackages;
        }
    }
    Con_Printf("Total: %lu files in %lu packages.\n", (unsigned long) totalFiles, (unsigned long)totalPackages);
    return true;
}

/**
 * C Wrapper API
 */

de::FS1* App_FileSystem()
{
    if(!fileSystem) throw de::Error("App_FileSystem", "File system not yet initialized");
    return fileSystem;
}

void F_Register(void)
{
    FS1::consoleRegister();
}

void F_Init(void)
{
    DENG_ASSERT(!fileSystem);
    fileSystem = new de::FS1();
}

void F_Shutdown(void)
{
    if(!fileSystem) return;
    delete fileSystem; fileSystem = 0;
}

void F_EndStartup(void)
{
    App_FileSystem()->endStartup();
}

void F_UnloadAllNonStartupFiles(int* numUnloaded)
{
    App_FileSystem()->unloadAllNonStartupFiles(numUnloaded);
}

void F_AddVirtualDirectoryMapping(char const* source, char const* destination)
{
    App_FileSystem()->mapPath(source, destination);
}

void F_AddLumpDirectoryMapping(char const* symbolicPath, char const* lumpName)
{
    App_FileSystem()->mapPathToLump(symbolicPath, lumpName);
}

void F_ResetFileIds(void)
{
    App_FileSystem()->resetFileIds();
}

boolean F_CheckFileId(char const* path)
{
    return App_FileSystem()->checkFileId(path);
}

int F_LumpCount(void)
{
    return App_FileSystem()->nameIndex().size();
}

int F_Access(char const* path)
{
    return App_FileSystem()->accessFile(path)? 1 : 0;
}

struct file1_s* F_AddFile2(char const* path, size_t baseOffset)
{
    return reinterpret_cast<struct file1_s*>(App_FileSystem()->addFile(path, baseOffset));
}

struct file1_s* F_AddFile(char const* path)
{
    return reinterpret_cast<struct file1_s*>(App_FileSystem()->addFile(path));
}

boolean F_RemoveFile2(char const* path, boolean permitRequired)
{
    return App_FileSystem()->removeFile(path, CPP_BOOL(permitRequired));
}

boolean F_RemoveFile(char const* path)
{
    return App_FileSystem()->removeFile(path);
}

int F_AddFiles(char const* const* paths, int num)
{
    return App_FileSystem()->addFiles(paths, num);
}

int F_RemoveFiles2(char const* const* filenames, int num, boolean permitRequired)
{
    return App_FileSystem()->removeFiles(filenames, num, CPP_BOOL(permitRequired));
}

int F_RemoveFiles(char const* const* filenames, int num)
{
    return App_FileSystem()->removeFiles(filenames, num);
}

void F_ReleaseFile(struct file1_s* file)
{
    if(!file) return;
    App_FileSystem()->releaseFile(*reinterpret_cast<de::File1*>(file));
}

struct filehandle_s* F_Open3(char const* path, char const* mode, size_t baseOffset, boolean allowDuplicate)
{
    try
    {
        return reinterpret_cast<struct filehandle_s*>(&App_FileSystem()->openFile(path, mode, baseOffset, CPP_BOOL(allowDuplicate)));
    }
    catch(FS1::NotFoundError const&)
    {} // Ignore error.
    return 0;
}

struct filehandle_s* F_Open2(char const* path, char const* mode, size_t baseOffset)
{
    try
    {
        return reinterpret_cast<struct filehandle_s*>(&App_FileSystem()->openFile(path, mode, baseOffset));
    }
    catch(FS1::NotFoundError const&)
    {} // Ignore error.
    return 0;
}

struct filehandle_s* F_Open(char const* path, char const* mode)
{
    try
    {
        return reinterpret_cast<struct filehandle_s*>(&App_FileSystem()->openFile(path, mode));
    }
    catch(FS1::NotFoundError const&)
    {} // Ignore error.
    return 0;
}

struct filehandle_s* F_OpenLump(lumpnum_t absoluteLumpNum)
{
    try
    {
        lumpnum_t lumpNum = absoluteLumpNum;
        de::File1& lump = App_FileSystem()->nameIndexForLump(lumpNum).lump(lumpNum);
        return reinterpret_cast<struct filehandle_s*>(&App_FileSystem()->openLump(lump));
    }
    catch(LumpIndex::NotFoundError const&)
    {} // Ignore error.
    return 0;
}

boolean F_IsValidLumpNum(lumpnum_t absoluteLumpNum)
{
    return App_FileSystem()->nameIndexForLump(absoluteLumpNum).isValidIndex(absoluteLumpNum);
}

lumpnum_t F_LumpNumForName(char const* name)
{
    try
    {
        return App_FileSystem()->lumpNumForName(name);
    }
    catch(FS1::NotFoundError const&)
    {} // Ignore error.
    return -1;
}

ddstring_t const* F_LumpName(lumpnum_t absoluteLumpNum)
{
    try
    {
        lumpnum_t lumpNum = absoluteLumpNum;
        de::File1 const& lump = App_FileSystem()->nameIndexForLump(lumpNum).lump(lumpNum);
        return lump.container().lumpName(lump.info().lumpIdx);
    }
    catch(LumpIndex::NotFoundError const&)
    {} // Ignore this error.
    static de::Str zeroLengthString;
    return zeroLengthString;
}

size_t F_LumpLength(lumpnum_t absoluteLumpNum)
{
    try
    {
        lumpnum_t lumpNum = absoluteLumpNum;
        de::File1 const& lump = App_FileSystem()->nameIndexForLump(lumpNum).lump(lumpNum);
        return lump.size();
    }
    catch(LumpIndex::NotFoundError const&)
    {} // Ignore this error.
    return 0;
}

uint F_LumpLastModified(lumpnum_t absoluteLumpNum)
{
    try
    {
        lumpnum_t lumpNum = absoluteLumpNum;
        de::File1 const& lump = App_FileSystem()->nameIndexForLump(lumpNum).lump(lumpNum);
        return lump.info().lastModified;
    }
    catch(LumpIndex::NotFoundError const&)
    {} // Ignore this error.
    return (uint)time(0);
}

void F_Close(struct filehandle_s* hndl)
{
    if(!hndl) return;
    App_FileSystem()->closeFile(*reinterpret_cast<de::FileHandle*>(hndl));
}

void F_Delete(struct filehandle_s* hndl)
{
    if(!hndl) return;
    App_FileSystem()->deleteFile(*reinterpret_cast<de::FileHandle*>(hndl));
}

ddstring_t const* F_Path(struct file1_s const* file)
{
    if(file) return reinterpret_cast<de::File1 const*>(file)->path();
    static de::Str zeroLengthString;
    return zeroLengthString;
}

void F_SetCustom(struct file1_s* file, boolean yes)
{
    if(!file) return;
    reinterpret_cast<de::File1*>(file)->setCustom(CPP_BOOL(yes));
}

size_t F_ReadLump(struct file1_s* _file, int lumpIdx, uint8_t* buffer)
{
    if(!_file) return 0;
    de::File1* file = reinterpret_cast<de::File1*>(_file);
    return file->readLump(lumpIdx, buffer);
}

size_t F_ReadLumpSection(struct file1_s* _file, int lumpIdx, uint8_t* buffer,
    size_t startOffset, size_t length)
{
    if(!_file) return 0;
    de::File1* file = reinterpret_cast<de::File1*>(_file);
    return file->readLump(lumpIdx, buffer, startOffset, length);
}

uint8_t const* F_CacheLump(struct file1_s* _file, int lumpIdx)
{
    if(!_file) return 0;
    de::File1* file = reinterpret_cast<de::File1*>(_file);
    return file->cacheLump(lumpIdx);
}

void F_UnlockLump(struct file1_s* _file, int lumpIdx)
{
    if(!_file) return;
    de::File1* file = reinterpret_cast<de::File1*>(_file);
    file->unlockLump(lumpIdx);
}

struct file1_s* F_FindFileForLumpNum2(lumpnum_t absoluteLumpNum, int* lumpIdx)
{
    try
    {
        lumpnum_t lumpNum = absoluteLumpNum;
        de::File1 const& lump = App_FileSystem()->nameIndexForLump(lumpNum).lump(lumpNum);
        if(lumpIdx) *lumpIdx = lump.info().lumpIdx;
        return reinterpret_cast<struct file1_s*>(&lump.container());
    }
    catch(LumpIndex::NotFoundError const&)
    {} // Ignore error.
    return 0;
}

struct file1_s* F_FindFileForLumpNum(lumpnum_t absoluteLumpNum)
{
    try
    {
        lumpnum_t lumpNum = absoluteLumpNum;
        de::File1 const& lump = App_FileSystem()->nameIndexForLump(lumpNum).lump(lumpNum);
        return reinterpret_cast<struct file1_s*>(&lump.container());
    }
    catch(LumpIndex::NotFoundError const&)
    {} // Ignore error.
    return 0;
}

ddstring_t const* F_LumpFilePath(lumpnum_t absoluteLumpNum)
{
    try
    {
        lumpnum_t lumpNum = absoluteLumpNum;
        de::File1 const& lump = App_FileSystem()->nameIndexForLump(lumpNum).lump(lumpNum);
        return lump.container().path();
    }
    catch(LumpIndex::NotFoundError const&)
    {} // Ignore this error.
    static de::Str const zeroLengthString;
    return zeroLengthString;
}

boolean F_LumpIsCustom(lumpnum_t absoluteLumpNum)
{
    try
    {
        lumpnum_t lumpNum = absoluteLumpNum;
        de::File1 const& lump = App_FileSystem()->nameIndexForLump(lumpNum).lump(lumpNum);
        return lump.container().hasCustom();
    }
    catch(LumpIndex::NotFoundError const&)
    {} // Ignore this error.
    return false;
}

AutoStr* F_ComposeLumpPath2(struct file1_s* _file, int lumpIdx, char delimiter)
{
    if(!_file) return AutoStr_NewStd();
    de::File1* file = reinterpret_cast<de::File1*>(_file);
    return file->composeLumpPath(lumpIdx, delimiter);
}

AutoStr* F_ComposeLumpPath(struct file1_s* _file, int lumpIdx)
{
    if(!_file) return AutoStr_NewStd();
    de::File1* file = reinterpret_cast<de::File1*>(_file);
    return file->composeLumpPath(lumpIdx);
}

/**
 * @defgroup pathToStringFlags  Path To String Flags.
 */
///@{
#define PTSF_QUOTED                 0x1 ///< Add double quotes around the path.
#define PTSF_TRANSFORM_EXCLUDE_DIR  0x2 ///< Exclude the directory; e.g., c:/doom/myaddon.wad -> myaddon.wad
#define PTSF_TRANSFORM_EXCLUDE_EXT  0x4 ///< Exclude the extension; e.g., c:/doom/myaddon.wad -> c:/doom/myaddon
///@}

#define DEFAULT_PATHTOSTRINGFLAGS (PTSF_QUOTED)

/**
 * @param flags         @ref pathToStringFlags
 * @param delimiter     If not @c NULL, path fragments in the resultant string
 *                      will be delimited by this.
 *
 * @return  New string containing a concatenated, possibly delimited set of all
 *      file paths in the list. Ownership of the string passes to the caller who
 *      should ensure to release it with Str_Delete() when no longer needed.
 *      Always returns a valid (but perhaps zero-length) string object.
 */
static ddstring_t* composeFilePathString(FS1::FileList& files, int flags = DEFAULT_PATHTOSTRINGFLAGS,
                                         char const* delimiter = " ")
{
    int maxLength, delimiterLength = (delimiter? (int)strlen(delimiter) : 0);
    int n, pLength;
    ddstring_t* str, buf;
    char const* p, *ext;

    Str_Init(&buf);

    // Determine the maximum number of characters we'll need.
    maxLength = 0;
    DENG2_FOR_EACH(i, files, FS1::FileList::const_iterator)
    {
        ddstring_t const* path = (*i)->file().path();

        if(!(flags & (PTSF_TRANSFORM_EXCLUDE_DIR|PTSF_TRANSFORM_EXCLUDE_EXT)))
        {
            // Caller wants the whole path plus name and extension (if present).
            maxLength += Str_Length(path);
        }
        else
        {
            if(flags & PTSF_TRANSFORM_EXCLUDE_DIR)
            {
                // Caller does not want the directory hierarchy.
                F_FileNameAndExtension(&buf, Str_Text(path));
                p = Str_Text(&buf);
                pLength = Str_Length(&buf);
            }
            else
            {
                p = Str_Text(path);
                pLength = Str_Length(path);
            }

            if(flags & PTSF_TRANSFORM_EXCLUDE_EXT)
            {
                // Caller does not want the file extension.
                ext = F_FindFileExtension(p);
                if(ext) ext -= 1/*dot separator*/;
            }
            else
            {
                ext = NULL;
            }

            if(ext)
            {
                maxLength += pLength - (pLength - (ext - p));
            }
            else
            {
                maxLength += pLength;
            }
        }

        if(flags & PTSF_QUOTED)
            maxLength += 1;
    }
    maxLength += files.count() * delimiterLength;

    // Composite final string.
    str = Str_New();
    Str_Reserve(str, maxLength);
    n = 0;
    DENG2_FOR_EACH(i, files, FS1::FileList::const_iterator)
    {
        ddstring_t const* path = (*i)->file().path();

        if(flags & PTSF_QUOTED)
            Str_AppendChar(str, '"');

        if(!(flags & (PTSF_TRANSFORM_EXCLUDE_DIR|PTSF_TRANSFORM_EXCLUDE_EXT)))
        {
            // Caller wants the whole path plus name and extension (if present).
            Str_Append(str, Str_Text(path));
        }
        else
        {
            if(flags & PTSF_TRANSFORM_EXCLUDE_DIR)
            {
                // Caller does not want the directory hierarchy.
                F_FileNameAndExtension(&buf, Str_Text(path));
                p = Str_Text(&buf);
                pLength = Str_Length(&buf);
            }
            else
            {
                p = Str_Text(path);
                pLength = Str_Length(path);
            }

            if(flags & PTSF_TRANSFORM_EXCLUDE_EXT)
            {
                // Caller does not want the file extension.
                ext = F_FindFileExtension(p);
                if(ext) ext -= 1/*dot separator*/;
            }
            else
            {
                ext = NULL;
            }

            if(ext)
            {
                Str_PartAppend(str, p, 0, pLength - (pLength - (ext - p)));
                maxLength += pLength - (pLength - (ext - p));
            }
            else
            {
                Str_Append(str, p);
            }
        }

        if(flags & PTSF_QUOTED)
            Str_AppendChar(str, '"');

        ++n;
        if(n != files.count())
            Str_Append(str, delimiter);
    }

    Str_Free(&buf);

    return str;
}

static bool findCustomFilesPredicate(de::FileHandle* hndl, void* /*parameters*/)
{
    de::File1& file = hndl->file();
    if(file.hasCustom())
    {
        ddstring_t const* path = file.path();
        if(stricmp(Str_Text(path) + Str_Length(path) - 3, "lmp"))
            return true; // Include this.
    }
    return false; // Not this.
}

/**
 * Compiles a list of file names, separated by @a delimiter.
 */
void F_ComposePWADFileList(char* outBuf, size_t outBufSize, const char* delimiter)
{
    if(!outBuf || 0 == outBufSize) return;
    memset(outBuf, 0, outBufSize);

    FS1::FileList foundFiles;
    if(!App_FileSystem()->findAll<de::Wad>(findCustomFilesPredicate, 0/*no params*/, foundFiles)) return;

    ddstring_t* str = composeFilePathString(foundFiles, PTSF_TRANSFORM_EXCLUDE_DIR, delimiter);
    strncpy(outBuf, Str_Text(str), outBufSize);
    Str_Delete(str);
}

uint F_CRCNumber(void)
{
    return App_FileSystem()->loadedFilesCRC();
}

lumpnum_t F_OpenAuxiliary2(char const* path, size_t baseOffset)
{
    return App_FileSystem()->openAuxiliary(path, baseOffset);
}

lumpnum_t F_OpenAuxiliary(char const* path)
{
    return App_FileSystem()->openAuxiliary(path);
}

void F_CloseAuxiliary(void)
{
    App_FileSystem()->closeAuxiliary();
}