Mercurial > hg > openttd
changeset 17905:b1f6f7bb52fa draft
(svn r22709) -Doc: Doxyment fileio.cpp.
author | alberth <alberth@openttd.org> |
---|---|
date | Mon, 01 Aug 2011 19:36:11 +0000 |
parents | d114b7d640d4 |
children | abfee8b3ca37 |
files | src/fileio.cpp |
diffstat | 1 files changed, 76 insertions(+), 12 deletions(-) [+] |
line wrap: on
line diff
--- a/src/fileio.cpp +++ b/src/fileio.cpp @@ -30,10 +30,6 @@ #include <sys/stat.h> #include <algorithm> -/*************************************************/ -/* FILE IO ROUTINES ******************************/ -/*************************************************/ - /** Size of the #Fio data buffer. */ #define FIO_BUFFER_SIZE 512 @@ -61,7 +57,10 @@ extern char *_config_file; extern char *_highscore_file; -/** Get current position in file. */ +/** + * Get position in the current file. + * @return Position in the file. + */ size_t FioGetPos() { return _fio.pos + (_fio.buffer - _fio.buffer_end); @@ -77,6 +76,11 @@ return _fio.shortnames[slot]; } +/** + * Seek in the current file. + * @param pos New position. + * @param mode Type of seek (\c SEEK_CUR means \a pos is relative to current position, \c SEEK_SET means \a pos is absolute). + */ void FioSeekTo(size_t pos, int mode) { if (mode == SEEK_CUR) pos += FioGetPos(); @@ -97,7 +101,11 @@ } #endif /* LIMITED_FDS */ -/* Seek to a file and a position */ +/** + * Switch to a different file and seek to a position. + * @param slot Slot number of the new file. + * @param pos New absolute position in the new file. + */ void FioSeekToFile(uint8 slot, size_t pos) { FILE *f; @@ -112,6 +120,10 @@ FioSeekTo(pos, SEEK_SET); } +/** + * Read a byte from the file. + * @return Read byte. + */ byte FioReadByte() { if (_fio.buffer == _fio.buffer_end) { @@ -125,6 +137,10 @@ return *_fio.buffer++; } +/** + * Skip \a n bytes ahead in the file. + * @param n Number of bytes to skip reading. + */ void FioSkipBytes(int n) { for (;;) { @@ -137,24 +153,41 @@ } } +/** + * Read a word (16 bits) from the file (in low endian format). + * @return Read word. + */ uint16 FioReadWord() { byte b = FioReadByte(); return (FioReadByte() << 8) | b; } +/** + * Read a double word (32 bits) from the file (in low endian format). + * @return Read word. + */ uint32 FioReadDword() { uint b = FioReadWord(); return (FioReadWord() << 16) | b; } +/** + * Read a block. + * @param ptr Destination buffer. + * @param size Number of bytes to read. + */ void FioReadBlock(void *ptr, size_t size) { FioSeekTo(FioGetPos(), SEEK_SET); _fio.pos += fread(ptr, 1, size, _fio.cur_fh); } +/** + * Close the file at the given slot number. + * @param slot File index to close. + */ static inline void FioCloseFile(int slot) { if (_fio.handles[slot] != NULL) { @@ -170,6 +203,7 @@ } } +/** Close all slotted open files. */ void FioCloseAll() { for (int i = 0; i != lengthof(_fio.handles); i++) { @@ -201,6 +235,11 @@ } #endif /* LIMITED_FDS */ +/** + * Open a slotted file. + * @param slot Index to assign. + * @param filename Name of the file at the disk. + */ void FioOpenFile(int slot, const char *filename) { FILE *f; @@ -252,7 +291,7 @@ /** * Check whether the given file exists - * @param filename the file to try for existance + * @param filename the file to try for existence. * @param subdir the subdirectory to look in * @return true if and only if the file can be opened */ @@ -266,7 +305,7 @@ } /** - * Test whether the fiven filename exists. + * Test whether the given filename exists. * @param filename the file to test. * @return true if and only if the file exists. */ @@ -319,7 +358,7 @@ #if !defined(WIN32) /* Be, as opening files, aware that sometimes the filename * might be in uppercase when it is in lowercase on the - * disk. Ofcourse Windows doesn't care about casing. */ + * disk. Of course Windows doesn't care about casing. */ if (strtolower(buf + strlen(_searchpaths[sp]) - 1) && FileExists(buf)) return buf; #endif } @@ -390,6 +429,13 @@ return f; } +/** + * Opens a file from inside a tar archive. + * @param entry The entry to open. + * @param filesize [out] If not \c NULL, size of the opened file. + * @return File handle of the opened file, or \c NULL if the file is not available. + * @note The file is read from within the tar file, and may not return \c EOF after reading the whole file. + */ FILE *FioFOpenFileTar(TarFileListEntry *entry, size_t *filesize) { FILE *f = fopen(entry->tar_filename, "rb"); @@ -400,7 +446,13 @@ return f; } -/** Opens OpenTTD files somewhere in a personal or global directory */ +/** + * Opens a OpenTTD file somewhere in a personal or global directory. + * @param filename Name of the file to open. + * @param subdir Subdirectory to open. + * @param filename Name of the file to open. + * @return File handle of the opened file, or \c NULL if the file is not available. + */ FILE *FioFOpenFile(const char *filename, const char *mode, Subdirectory subdir, size_t *filesize) { FILE *f = NULL; @@ -483,7 +535,7 @@ * Appends, if necessary, the path separator character to the end of the string. * It does not add the path separator to zero-sized strings. * @param buf string to append the separator to - * @param buflen the length of the buf + * @param buflen the length of \a buf. * @return true iff the operation succeeded */ bool AppendPathSeparator(char *buf, size_t buflen) @@ -526,6 +578,10 @@ return dest; } +/** + * Find the first directory in a tar archive. + * @param tarname the name of the tar archive to look in. + */ const char *FioTarFirstDir(const char *tarname) { TarList::iterator it = _tar_list.find(tarname); @@ -561,7 +617,7 @@ /** * Simplify filenames from tars. - * Replace '/' by PATHSEPCHAR, and force 'name' to lowercase. + * Replace '/' by #PATHSEPCHAR, and force 'name' to lowercase. * @param name Filename to process. */ static void SimplifyFileName(char *name) @@ -1141,6 +1197,14 @@ } } +/** + * Load a file into memory. + * @param filename Name of the file to load. + * @param lenp [out] Length of loaded data. + * @param maxsize Maximum size to load. + * @return Pointer to new memory containing the loaded data, or \c NULL if loading failed. + * @note If \a maxsize less than the length of the file, loading fails. + */ void *ReadFileToMem(const char *filename, size_t *lenp, size_t maxsize) { FILE *in = fopen(filename, "rb");