summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authoralberth <alberth@openttd.org>2011-08-01 19:36:11 +0000
committeralberth <alberth@openttd.org>2011-08-01 19:36:11 +0000
commit89c7193b8fe72d043bdeb9e44963adfed3b72134 (patch)
tree8b7d1106b6fdf5ef2a18d0efa826ca39e42a4868
parent3fb66890eeb3689e645fa6d520aecc0c0908031f (diff)
downloadopenttd-89c7193b8fe72d043bdeb9e44963adfed3b72134.tar.xz
(svn r22709) -Doc: Doxyment fileio.cpp.
-rw-r--r--src/fileio.cpp88
1 files changed, 76 insertions, 12 deletions
diff --git a/src/fileio.cpp b/src/fileio.cpp
index 7ac5ce7da..d4eab410c 100644
--- 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 @@ static bool _do_scan_working_directory = true;
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 @@ const char *FioGetFilename(uint8 slot)
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 @@ static void FioRestoreFile(int slot)
}
#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 @@ void FioSeekToFile(uint8 slot, size_t pos)
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 @@ byte FioReadByte()
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 @@ void FioSkipBytes(int n)
}
}
+/**
+ * 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 @@ static inline void FioCloseFile(int slot)
}
}
+/** Close all slotted open files. */
void FioCloseAll()
{
for (int i = 0; i != lengthof(_fio.handles); i++) {
@@ -201,6 +235,11 @@ static void FioFreeHandle()
}
#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 @@ static TarLinkList _tar_linklist; ///< List of directory links
/**
* 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 @@ bool FioCheckFileExists(const char *filename, Subdirectory subdir)
}
/**
- * 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 @@ char *FioFindFullPath(char *buf, size_t buflen, Subdirectory subdir, const char
#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 @@ static FILE *FioFOpenFileSp(const char *filename, const char *mode, Searchpath s
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 @@ FILE *FioFOpenFileTar(TarFileListEntry *entry, size_t *filesize)
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 @@ static void FioCreateDirectory(const char *name)
* 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 @@ char *BuildWithFullPath(const char *dir)
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 @@ void FioTarAddLink(const char *src, const char *dest)
/**
* 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 @@ void SanitizeFilename(char *filename)
}
}
+/**
+ * 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");