Skip to content

Commit

Permalink
Cleanup
Browse files Browse the repository at this point in the history
  • Loading branch information
@danij-deng
danij-deng committed Oct 3, 2012
1 parent ae85f34 commit 323b5dd
Show file tree
Hide file tree
Showing 3 changed files with 336 additions and 408 deletions.
170 changes: 83 additions & 87 deletions doomsday/engine/portable/include/fs_main.h
View file
@@ -1,45 +1,41 @@
/**\file fs_main.h
*\section License
* License: GPL
* Online License Link: http://www.gnu.org/licenses/gpl.html
*
*\author Copyright © 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
*\author Copyright © 2009-2012 Daniel Swanson <danij@dengine.net>
*
* 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
*/

/**
* @file fs_main.h
*
* Virtual file system and file (input) stream abstraction layer.
*
* This version supports runtime (un)loading.
*
* File input. Can read from real files or WAD lumps. Note that
* reading from WAD lumps means that a copy is taken of the lump when
* the corresponding 'file' is opened. With big files this uses
* considerable memory and time.
* File input. Can read from real files or WAD lumps. Note that reading from
* WAD lumps means that a copy is taken of the lump when the corresponding
* 'file' is opened. With big files this uses considerable memory and time.
*
* Internally, the cache has two parts: the Primary cache, which is loaded
* from data files, and the Auxiliary cache, which is generated at runtime.
* To outsiders, there is no difference between these two caches. The
* only visible difference is that lumps in the auxiliary cache use indices
* starting from AUXILIARY_BASE.
* Internally, the cache has two parts: the Primary cache, which is loaded from
* data files, and the Auxiliary cache, which is generated at runtime. To
* outsiders, there is no difference between these two caches. The only visible
* difference is that lumps in the auxiliary cache use indices starting from
* AUXILIARY_BASE.
*
* Functions that don't know the lumpnum of file will have to check both
* the primary and the auxiliary caches (e.g., F_CheckLumpNumForName()).
*
* @ingroup fs
*
* @author Copyright &copy; 2003-2012 Jaakko Keränen <jaakko.keranen@iki.fi>
* @author Copyright &copy; 2009-2012 Daniel Swanson <danij@dengine.net>
*
* @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>
*/

#ifndef LIBDENG_FILESYS_MAIN_H
Expand Down Expand Up @@ -74,7 +70,7 @@ void F_Init(void);
void F_Shutdown(void);

/**
* \post No more WADs will be loaded in startup mode.
* @post No more WADs will be loaded in startup mode.
*/
void F_EndStartup(void);

Expand All @@ -94,7 +90,7 @@ void F_ResetFileIds(void);
* Calculate an identifier for the file based on its full path name.
* The identifier is the MD5 hash of the path.
*/
void F_GenerateFileId(const char* str, byte identifier[16]);
void F_GenerateFileId(char const* str, byte identifier[16]);

void F_PrintFileId(byte identifier[16]);

Expand All @@ -104,10 +100,10 @@ void F_PrintFileId(byte identifier[16]);
* @return @c true if the given file can be opened, or
* @c false, if it has already been opened.
*/
boolean F_CheckFileId(const char* path);
boolean F_CheckFileId(char const* path);

/// @return @c true if the FileId associated with @a path was released.
boolean F_ReleaseFileId(const char* path);
boolean F_ReleaseFileId(char const* path);

/// @return Number of files in the currently active primary LumpDirectory.
int F_LumpCount(void);
Expand All @@ -116,11 +112,11 @@ boolean F_IsValidLumpNum(lumpnum_t absoluteLumpNum);

boolean F_LumpIsCustom(lumpnum_t absoluteLumpNum);

const char* F_LumpName(lumpnum_t absoluteLumpNum);
char const* F_LumpName(lumpnum_t absoluteLumpNum);

size_t F_LumpLength(lumpnum_t absoluteLumpNum);

const char* F_LumpSourceFile(lumpnum_t absoluteLumpNum);
char const* F_LumpSourceFile(lumpnum_t absoluteLumpNum);

uint F_LumpLastModified(lumpnum_t absoluteLumpNum);

Expand All @@ -129,49 +125,51 @@ uint F_LumpLastModified(lumpnum_t absoluteLumpNum);
*
* @post The active LumpDirectory may have changed!
*
* @param absoluteLumpNum Logical lumpnum associated to the file being looked up.
* @param lumpIdx If not @c NULL the translated lumpnum within the owning file object is written here.
* @param absoluteLumpNum Logical lumpnum associated to the file being looked up.
* @param lumpIdx If not @c NULL the translated lumpnum within the owning
* file object is written here.
*
* @return Found file object else @c NULL
*/
AbstractFile* F_FindFileForLumpNum2(lumpnum_t absoluteLumpNum, int* lumpIdx);
AbstractFile* F_FindFileForLumpNum(lumpnum_t absoluteLumpNum);

const LumpInfo* F_FindInfoForLumpNum2(lumpnum_t absoluteLumpNum, int* lumpIdx);
const LumpInfo* F_FindInfoForLumpNum(lumpnum_t absoluteLumpNum);
LumpInfo const* F_FindInfoForLumpNum2(lumpnum_t absoluteLumpNum, int* lumpIdx);
LumpInfo const* F_FindInfoForLumpNum(lumpnum_t absoluteLumpNum);

lumpnum_t F_CheckLumpNumForName2(const char* name, boolean silent);
lumpnum_t F_CheckLumpNumForName(const char* name);
lumpnum_t F_CheckLumpNumForName2(char const* name, boolean silent);
lumpnum_t F_CheckLumpNumForName(char const* name);

/**
* Try to open the specified WAD archive into the auxiliary lump cache.
* @return Base index for lumps in this archive.
*/
lumpnum_t F_OpenAuxiliary3(const char* fileName, size_t baseOffset, boolean silent);
lumpnum_t F_OpenAuxiliary2(const char* fileName, size_t baseOffset); /* silent = false */
lumpnum_t F_OpenAuxiliary(const char* fileName); /* baseOffset = 0 */
lumpnum_t F_OpenAuxiliary3(char const* fileName, size_t baseOffset, boolean silent);
lumpnum_t F_OpenAuxiliary2(char const* fileName, size_t baseOffset); /* silent = false */
lumpnum_t F_OpenAuxiliary(char const* fileName); /* baseOffset = 0 */

void F_CloseAuxiliary(void);

/**
* Find a lump in the Zip LumpDirectory.
*
* @param path Path to search for. Relative paths are made absolute if necessary.
* @param lumpIdx If not @c NULL the translated lumpnum within the owning file object is written here.
* @param path Path to search for. Relative paths are made absolute if necessary.
* @param lumpIdx If not @c NULL the translated lumpnum within the owning file object is written here.
* @return File system object representing the file which contains the found lump else @c NULL.
*/
AbstractFile* F_FindLumpFile(const char* path, int* lumpIdx);
AbstractFile* F_FindLumpFile(char const* path, int* lumpIdx);

/**
* Files with a .wad extension are archived data files with multiple 'lumps',
* other files are single lumps whose base filename will become the lump name.
*
* @param path Path to the file to be opened. Either a "real" file in the local
* file system, or a "virtual" file in the virtual file system.
* @param baseOffset Offset from the start of the file in bytes to begin.
* @param path Path to the file to be opened. Either a "real" file in the local
* file system, or a "virtual" file in the virtual file system.
* @param baseOffset Offset from the start of the file in bytes to begin.
* @param allowDuplicate @c true = allow opening multiple copies of the same file.
* @return Handle to the opened file if the operation is successful, else @c NULL.
*/
DFile* F_AddFile(const char* path, size_t baseOffset, boolean allowDuplicate);
DFile* F_AddFile(char const* path, size_t baseOffset, boolean allowDuplicate);

/**
* Attempt to remove a file from the virtual file system.
Expand All @@ -180,35 +178,35 @@ DFile* F_AddFile(const char* path, size_t baseOffset, boolean allowDuplicate);
* by the currently loaded Game.
* @return @c true if the operation is successful.
*/
boolean F_RemoveFile(const char* path, boolean permitRequired);
boolean F_RemoveFile(char const* path, boolean permitRequired);

boolean F_AddFiles(const char* const* paths, size_t num, boolean allowDuplicate);
boolean F_RemoveFiles(const char* const* paths, size_t num, boolean permitRequired);
boolean F_AddFiles(char const* const* paths, int num, boolean allowDuplicate);
boolean F_RemoveFiles(char const* const* paths, int num, boolean permitRequired);

/**
* @return @c true if the file can be opened for reading.
*/
int F_Access(const char* path);
int F_Access(char const* path);

/**
* Opens the given file (will be translated) for reading.
*
* \post If @a allowDuplicate = @c false a new file ID for this will have been
* @post If @a allowDuplicate = @c false a new file ID for this will have been
* added to the list of known file identifiers if this file hasn't yet been
* opened. It is the responsibility of the caller to release this identifier when done.
*
* @param path Possibly relative or mapped path to the resource being opened.
* @param mode
* 't' = text mode (with real files, lumps are always binary)
* 'b' = binary
* 'f' = must be a real file in the local file system
* @param path Possibly relative or mapped path to the resource being opened.
* @param mode 't' = text mode (with real files, lumps are always binary)
* 'b' = binary
* 'f' = must be a real file in the local file system
* @param baseOffset Offset from the start of the file in bytes to begin.
* @param allowDuplicate @c false = open only if not already opened.
*
* @return Opened file reference/handle else @c NULL.
*/
DFile* F_Open3(const char* path, const char* mode, size_t baseOffset, boolean allowDuplicate);
DFile* F_Open2(const char* path, const char* mode, size_t baseOffset); /* allowDuplicate = true */
DFile* F_Open(const char* path, const char* mode); /* baseOffset = 0 */
DFile* F_Open3(char const* path, char const* mode, size_t baseOffset, boolean allowDuplicate);
DFile* F_Open2(char const* path, char const* mode, size_t baseOffset/*, allowDuplicate = true */);
DFile* F_Open(char const* path, char const* mode/*, baseOffset = 0 */);

/**
* Try to locate the specified lump for reading.
Expand All @@ -222,12 +220,13 @@ DFile* F_OpenLump(lumpnum_t lumpNum);
/**
* Write the data associated with the specified lump index to @a fileName.
*
* @param lumpNum Absolute index of the lump to open.
* @param lumpNum Absolute index of the lump to open.
* @param fileName If not @c NULL write the associated data to this path.
* Can be @c NULL in which case the fileName will be chosen automatically.
* Can be @c NULL in which case the fileName will be chosen automatically.
*
* @return @c true iff successful.
*/
boolean F_DumpLump(lumpnum_t lumpNum, const char* fileName);
boolean F_DumpLump(lumpnum_t lumpNum, char const* fileName);

/**
* Write data into a file.
Expand All @@ -238,36 +237,36 @@ boolean F_DumpLump(lumpnum_t lumpNum, const char* fileName);
*
* @return @c true if successful, otherwise @c false.
*/
boolean F_Dump(const void *data, size_t size, const char* path);
boolean F_Dump(void const* data, size_t size, char const* path);

/**
* @return The time when the file was last modified, as seconds since
* the Epoch else zero if the file is not found.
*/
uint F_GetLastModified(const char* fileName);
uint F_GetLastModified(char const* fileName);

void F_InitVirtualDirectoryMappings(void);

/**
* Add a new virtual directory mapping from source to destination in the vfs.
* \note Paths will be transformed into absolute paths if needed.
* @note Paths will be transformed into absolute paths if needed.
*/
void F_AddVirtualDirectoryMapping(const char* source, const char* destination);
void F_AddVirtualDirectoryMapping(char const* source, char const* destination);

/// \note Should be called after WADs have been processed.
/// @note Should be called after WADs have been processed.
void F_InitLumpDirectoryMappings(void);

/**
* Add a new lump mapping so that @a lumpName becomes visible as @a symbolicPath
* throughout the vfs.
* \note @a symbolicPath will be transformed into an absolute path if needed.
* @note @a symbolicPath will be transformed into an absolute path if needed.
*/
void F_AddLumpDirectoryMapping(const char* lumpName, const char* symbolicPath);
void F_AddLumpDirectoryMapping(char const* lumpName, char const* symbolicPath);

/**
* Compiles a list of PWAD file names, separated by @a delimiter.
*/
void F_GetPWADFileNames(char* buf, size_t bufSize, const char* delimiter);
void F_GetPWADFileNames(char* buf, size_t bufSize, char const* delimiter);

/**
* Calculate a CRC for the loaded file list.
Expand All @@ -288,12 +287,12 @@ AutoStr* F_ComposeLumpPath(AbstractFile* file, int lumpIdx); /*delimiter='/'*/

struct pathdirectorynode_s* F_LumpDirectoryNode(AbstractFile* file, int lumpIdx);

const LumpInfo* F_LumpInfo(AbstractFile* file, int lumpIdx);
LumpInfo const* F_LumpInfo(AbstractFile* file, int lumpIdx);

size_t F_ReadLumpSection(AbstractFile* file, int lumpIdx, uint8_t* buffer,
size_t startOffset, size_t length);
size_t startOffset, size_t length);

const uint8_t* F_CacheLump(AbstractFile* file, int lumpIdx);
uint8_t const* F_CacheLump(AbstractFile* file, int lumpIdx);

void F_UnlockLump(AbstractFile* file, int lumpIdx);

Expand All @@ -304,11 +303,8 @@ void F_UnlockLump(AbstractFile* file, int lumpIdx);
*
* @param flags @see searchPathFlags
*/
int F_AllResourcePaths2(const char* searchPath, int flags,
int (*callback) (const ddstring_t* path, PathDirectoryNodeType type, void* paramaters),
void* paramaters);
int F_AllResourcePaths(const char* searchPath, int flags,
int (*callback) (const ddstring_t* path, PathDirectoryNodeType type, void* paramaters));
int F_AllResourcePaths2(char const* searchPath, int flags, int (*callback) (ddstring_t const* path, PathDirectoryNodeType type, void* parameters), void* parameters);
int F_AllResourcePaths(char const* searchPath, int flags, int (*callback) (ddstring_t const* path, PathDirectoryNodeType type, void* parameters)/*, parameters = 0 */);

#ifdef __cplusplus
} // extern "C"
Expand Down

0 comments on commit 323b5dd

Please sign in to comment.