neo/framework/FileSystem.h

   1 /*
   2 ===========================================================================
   3
   4 Doom 3 GPL Source Code
   5 Copyright (C) 1999-2011 id Software LLC, a ZeniMax Media company.
   6
   7 This file is part of the Doom 3 GPL Source Code (?Doom 3 Source Code?).
   8
   9 Doom 3 Source Code is free software: you can redistribute it and/or modify
  10 it under the terms of the GNU General Public License as published by
  11 the Free Software Foundation, either version 3 of the License, or
  12 (at your option) any later version.
  13
  14 Doom 3 Source Code is distributed in the hope that it will be useful,
  15 but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 GNU General Public License for more details.
  18
  19 You should have received a copy of the GNU General Public License
  20 along with Doom 3 Source Code.  If not, see <http://www.gnu.org/licenses/>.
  21
  22 In addition, the Doom 3 Source Code is also subject to certain additional terms. You should have received a copy of these additional terms immediately following the terms and conditions of the GNU General Public License which accompanied the Doom 3 Source Code.  If not, please request a copy in writing from id Software at the address below.
  23
  24 If you have questions concerning this license or the applicable additional terms, you may contact in writing id Software LLC, c/o ZeniMax Media Inc., Suite 120, Rockville, Maryland 20850 USA.
  25
  26 ===========================================================================
  27 */
  28
  29 #ifndef __FILESYSTEM_H__
  30 #define __FILESYSTEM_H__
  31
  32 /*
  33 ===============================================================================
  34
  35         File System
  36
  37         No stdio calls should be used by any part of the game, because of all sorts
  38         of directory and separator char issues. Throughout the game a forward slash
  39         should be used as a separator. The file system takes care of the conversion
  40         to an OS specific separator. The file system treats all file and directory
  41         names as case insensitive.
  42
  43         The following cvars store paths used by the file system:
  44
  45         "fs_basepath"           path to local install, read-only
  46         "fs_savepath"           path to config, save game, etc. files, read & write
  47         "fs_cdpath"                     path to cd, read-only
  48         "fs_devpath"            path to files created during development, read & write
  49
  50         The base path for file saving can be set to "fs_savepath" or "fs_devpath".
  51
  52 ===============================================================================
  53 */
  54
  55 static const ID_TIME_T          FILE_NOT_FOUND_TIMESTAMP        = 0xFFFFFFFF;
  56 static const int                MAX_PURE_PAKS                           = 128;
  57 static const int                MAX_OSPATH                                      = 256;
  58
  59 // modes for OpenFileByMode. used as bit mask internally
  60 typedef enum {
  61         FS_READ         = 0,
  62         FS_WRITE        = 1,
  63         FS_APPEND       = 2
  64 } fsMode_t;
  65
  66 typedef enum {
  67         PURE_OK,                // we are good to connect as-is
  68         PURE_RESTART,   // restart required
  69         PURE_MISSING,   // pak files missing on the client
  70         PURE_NODLL              // no DLL could be extracted
  71 } fsPureReply_t;
  72
  73 typedef enum {
  74         DLTYPE_URL,
  75         DLTYPE_FILE
  76 } dlType_t;
  77
  78 typedef enum {
  79         DL_WAIT,                // waiting in the list for beginning of the download
  80         DL_INPROGRESS,  // in progress
  81         DL_DONE,                // download completed, success
  82         DL_ABORTING,    // this one can be set during a download, it will force the next progress callback to abort - then will go to DL_FAILED
  83         DL_FAILED
  84 } dlStatus_t;
  85
  86 typedef enum {
  87         FILE_EXEC,
  88         FILE_OPEN
  89 } dlMime_t;
  90
  91 typedef enum {
  92         FIND_NO,
  93         FIND_YES,
  94         FIND_ADDON
  95 } findFile_t;
  96
  97 typedef struct urlDownload_s {
  98         idStr                           url;
  99         char                            dlerror[ MAX_STRING_CHARS ];
 100         int                                     dltotal;
 101         int                                     dlnow;
 102         int                                     dlstatus;
 103         dlStatus_t                      status;
 104 } urlDownload_t;
 105
 106 typedef struct fileDownload_s {
 107         int                                     position;
 108         int                                     length;
 109         void *                          buffer;
 110 } fileDownload_t;
 111
 112 typedef struct backgroundDownload_s {
 113         struct backgroundDownload_s     *next;  // set by the fileSystem
 114         dlType_t                        opcode;
 115         idFile *                        f;
 116         fileDownload_t          file;
 117         urlDownload_t           url;
 118         volatile bool           completed;
 119 } backgroundDownload_t;
 120
 121 // file list for directory listings
 122 class idFileList {
 123         friend class idFileSystemLocal;
 124 public:
 125         const char *                    GetBasePath( void ) const { return basePath; }
 126         int                                             GetNumFiles( void ) const { return list.Num(); }
 127         const char *                    GetFile( int index ) const { return list[index]; }
 128         const idStrList &               GetList( void ) const { return list; }
 129
 130 private:
 131         idStr                                   basePath;
 132         idStrList                               list;
 133 };
 134
 135 // mod list
 136 class idModList {
 137         friend class idFileSystemLocal;
 138 public:
 139         int                                             GetNumMods( void ) const { return mods.Num(); }
 140         const char *                    GetMod( int index ) const { return mods[index]; }
 141         const char *                    GetDescription( int index ) const { return descriptions[index]; }
 142
 143 private:
 144         idStrList                               mods;
 145         idStrList                               descriptions;
 146 };
 147
 148 class idFileSystem {
 149 public:
 150         virtual                                 ~idFileSystem() {}
 151                                                         // Initializes the file system.
 152         virtual void                    Init( void ) = 0;
 153                                                         // Restarts the file system.
 154         virtual void                    Restart( void ) = 0;
 155                                                         // Shutdown the file system.
 156         virtual void                    Shutdown( bool reloading ) = 0;
 157                                                         // Returns true if the file system is initialized.
 158         virtual bool                    IsInitialized( void ) const = 0;
 159                                                         // Returns true if we are doing an fs_copyfiles.
 160         virtual bool                    PerformingCopyFiles( void ) const = 0;
 161                                                         // Returns a list of mods found along with descriptions
 162                                                         // 'mods' contains the directory names to be passed to fs_game
 163                                                         // 'descriptions' contains a free form string to be used in the UI
 164         virtual idModList *             ListMods( void ) = 0;
 165                                                         // Frees the given mod list
 166         virtual void                    FreeModList( idModList *modList ) = 0;
 167                                                         // Lists files with the given extension in the given directory.
 168                                                         // Directory should not have either a leading or trailing '/'
 169                                                         // The returned files will not include any directories or '/' unless fullRelativePath is set.
 170                                                         // The extension must include a leading dot and may not contain wildcards.
 171                                                         // If extension is "/", only subdirectories will be returned.
 172         virtual idFileList *    ListFiles( const char *relativePath, const char *extension, bool sort = false, bool fullRelativePath = false, const char* gamedir = NULL ) = 0;
 173                                                         // Lists files in the given directory and all subdirectories with the given extension.
 174                                                         // Directory should not have either a leading or trailing '/'
 175                                                         // The returned files include a full relative path.
 176                                                         // The extension must include a leading dot and may not contain wildcards.
 177         virtual idFileList *    ListFilesTree( const char *relativePath, const char *extension, bool sort = false, const char* gamedir = NULL ) = 0;
 178                                                         // Frees the given file list.
 179         virtual void                    FreeFileList( idFileList *fileList ) = 0;
 180                                                         // Converts a relative path to a full OS path.
 181         virtual const char *    OSPathToRelativePath( const char *OSPath ) = 0;
 182                                                         // Converts a full OS path to a relative path.
 183         virtual const char *    RelativePathToOSPath( const char *relativePath, const char *basePath = "fs_devpath" ) = 0;
 184                                                         // Builds a full OS path from the given components.
 185         virtual const char *    BuildOSPath( const char *base, const char *game, const char *relativePath ) = 0;
 186                                                         // Creates the given OS path for as far as it doesn't exist already.
 187         virtual void                    CreateOSPath( const char *OSPath ) = 0;
 188                                                         // Returns true if a file is in a pak file.
 189         virtual bool                    FileIsInPAK( const char *relativePath ) = 0;
 190                                                         // Returns a space separated string containing the checksums of all referenced pak files.
 191                                                         // will call SetPureServerChecksums internally to restrict itself
 192         virtual void                    UpdatePureServerChecksums( void ) = 0;
 193                                                         // setup the mapping of OS -> game pak checksum
 194         virtual bool                    UpdateGamePakChecksums( void ) = 0;
 195                                                         // 0-terminated list of pak checksums
 196                                                         // if pureChecksums[ 0 ] == 0, all data sources will be allowed
 197                                                         // otherwise, only pak files that match one of the checksums will be checked for files
 198                                                         // with the sole exception of .cfg files.
 199                                                         // the function tries to configure pure mode from the paks already referenced and this new list
 200                                                         // it returns wether the switch was successfull, and sets the missing checksums
 201                                                         // the process is verbosive when fs_debug 1
 202         virtual fsPureReply_t   SetPureServerChecksums( const int pureChecksums[ MAX_PURE_PAKS ], int gamePakChecksum, int missingChecksums[ MAX_PURE_PAKS ], int *missingGamePakChecksum ) = 0;
 203                                                         // fills a 0-terminated list of pak checksums for a client
 204                                                         // if OS is -1, give the current game pak checksum. if >= 0, lookup the game pak table (server only)
 205         virtual void                    GetPureServerChecksums( int checksums[ MAX_PURE_PAKS ], int OS, int *gamePakChecksum ) = 0;
 206                                                         // before doing a restart, force the pure list and the search order
 207                                                         // if the given checksum list can't be completely processed and set, will error out
 208         virtual void                    SetRestartChecksums( const int pureChecksums[ MAX_PURE_PAKS ], int gamePakChecksum ) = 0;
 209                                                         // equivalent to calling SetPureServerChecksums with an empty list
 210         virtual void                    ClearPureChecksums( void ) = 0;
 211                                                         // get a mask of supported OSes. if not pure, returns -1
 212         virtual int                             GetOSMask( void ) = 0;
 213                                                         // Reads a complete file.
 214                                                         // Returns the length of the file, or -1 on failure.
 215                                                         // A null buffer will just return the file length without loading.
 216                                                         // A null timestamp will be ignored.
 217                                                         // As a quick check for existance. -1 length == not present.
 218                                                         // A 0 byte will always be appended at the end, so string ops are safe.
 219                                                         // The buffer should be considered read-only, because it may be cached for other uses.
 220         virtual int                             ReadFile( const char *relativePath, void **buffer, ID_TIME_T *timestamp = NULL ) = 0;
 221                                                         // Frees the memory allocated by ReadFile.
 222         virtual void                    FreeFile( void *buffer ) = 0;
 223                                                         // Writes a complete file, will create any needed subdirectories.
 224                                                         // Returns the length of the file, or -1 on failure.
 225         virtual int                             WriteFile( const char *relativePath, const void *buffer, int size, const char *basePath = "fs_savepath" ) = 0;
 226                                                         // Removes the given file.
 227         virtual void                    RemoveFile( const char *relativePath ) = 0;
 228                                                         // Opens a file for reading.
 229         virtual idFile *                OpenFileRead( const char *relativePath, bool allowCopyFiles = true, const char* gamedir = NULL ) = 0;
 230                                                         // Opens a file for writing, will create any needed subdirectories.
 231         virtual idFile *                OpenFileWrite( const char *relativePath, const char *basePath = "fs_savepath" ) = 0;
 232                                                         // Opens a file for writing at the end.
 233         virtual idFile *                OpenFileAppend( const char *filename, bool sync = false, const char *basePath = "fs_basepath" ) = 0;
 234                                                         // Opens a file for reading, writing, or appending depending on the value of mode.
 235         virtual idFile *                OpenFileByMode( const char *relativePath, fsMode_t mode ) = 0;
 236                                                         // Opens a file for reading from a full OS path.
 237         virtual idFile *                OpenExplicitFileRead( const char *OSPath ) = 0;
 238                                                         // Opens a file for writing to a full OS path.
 239         virtual idFile *                OpenExplicitFileWrite( const char *OSPath ) = 0;
 240                                                         // Closes a file.
 241         virtual void                    CloseFile( idFile *f ) = 0;
 242                                                         // Returns immediately, performing the read from a background thread.
 243         virtual void                    BackgroundDownload( backgroundDownload_t *bgl ) = 0;
 244                                                         // resets the bytes read counter
 245         virtual void                    ResetReadCount( void ) = 0;
 246                                                         // retrieves the current read count
 247         virtual int                             GetReadCount( void ) = 0;
 248                                                         // adds to the read count
 249         virtual void                    AddToReadCount( int c ) = 0;
 250                                                         // look for a dynamic module
 251         virtual void                    FindDLL( const char *basename, char dllPath[ MAX_OSPATH ], bool updateChecksum ) = 0;
 252                                                         // case sensitive filesystems use an internal directory cache
 253                                                         // the cache is cleared when calling OpenFileWrite and RemoveFile
 254                                                         // in some cases you may need to use this directly
 255         virtual void                    ClearDirCache( void ) = 0;
 256
 257                                                         // is D3XP installed? even if not running it atm
 258         virtual bool                    HasD3XP( void ) = 0;
 259                                                         // are we using D3XP content ( through a real d3xp run or through a double mod )
 260         virtual bool                    RunningD3XP( void ) = 0;
 261
 262                                                         // don't use for large copies - allocates a single memory block for the copy
 263         virtual void                    CopyFile( const char *fromOSPath, const char *toOSPath ) = 0;
 264
 265                                                         // lookup a relative path, return the size or 0 if not found
 266         virtual int                             ValidateDownloadPakForChecksum( int checksum, char path[ MAX_STRING_CHARS ], bool isGamePak ) = 0;
 267
 268         virtual idFile *                MakeTemporaryFile( void ) = 0;
 269
 270                                                         // make downloaded pak files known so pure negociation works next time
 271         virtual int                             AddZipFile( const char *path ) = 0;
 272
 273                                                         // look for a file in the loaded paks or the addon paks
 274                                                         // if the file is found in addons, FS's internal structures are ready for a reloadEngine
 275         virtual findFile_t              FindFile( const char *path, bool scheduleAddons = false ) = 0;
 276
 277                                                         // get map/addon decls and take into account addon paks that are not on the search list
 278                                                         // the decl 'name' is in the "path" entry of the dict
 279         virtual int                             GetNumMaps() = 0;
 280         virtual const idDict *  GetMapDecl( int i ) = 0;
 281         virtual void                    FindMapScreenshot( const char *path, char *buf, int len ) = 0;
 282
 283                                                         // ignore case and seperator char distinctions
 284         virtual bool                    FilenameCompare( const char *s1, const char *s2 ) const = 0;
 285 };
 286
 287 extern idFileSystem *           fileSystem;
 288
 289 #endif /* !__FILESYSTEM_H__ */