ScummVM
Common::File Class Reference

TODO: vital to document this core class properly!!! For both users and implementors. More...

#include <file.h>

Inheritance diagram for Common::File:
Collaboration diagram for Common::File:

Public Member Functions

 File ()
 
virtual ~File ()
 
virtual bool open (const String &filename)
 Try to open the file with the given filename, by searching SearchMan. More...
 
virtual bool open (const String &filename, Archive &archive)
 Try to open the file with the given filename from within the given archive. More...
 
virtual bool open (const FSNode &node)
 Try to open the file corresponding to the give node. More...
 
virtual bool open (SeekableReadStream *stream, const String &name)
 Try to 'open' the given stream. More...
 
virtual void close ()
 Close the file, if open. More...
 
bool isOpen () const
 Checks if the object opened a file successfully. More...
 
const char * getName () const
 Returns the filename of the opened file for debugging purposes. More...
 
bool err () const
 Returns true if an I/O failure occurred. More...
 
void clearErr ()
 Reset the I/O error status as returned by err(). More...
 
bool eos () const
 Returns true if a read failed because the stream end has been reached. More...
 
int32 pos () const
 Obtains the current value of the stream position indicator of the stream. More...
 
int32 size () const
 Obtains the total size of the stream, measured in bytes. More...
 
bool seek (int32 offs, int whence=SEEK_SET)
 Sets the stream position indicator for the stream. More...
 
uint32 read (void *dataPtr, uint32 dataSize)
 Read data from the stream. More...
 
- Public Member Functions inherited from Common::SeekableReadStream
virtual bool skip (uint32 offset)
 TODO: Get rid of this??? Or keep it and document it. More...
 
virtual char * readLine (char *s, size_t bufSize)
 Reads at most one less than the number of characters specified by bufSize from the and stores them in the string buf. More...
 
virtual String readLine ()
 Reads a full line and returns it as a Common::String. More...
 
void hexdump (int len, int bytesPerLine=16, int startOffset=0)
 Print a hexdump of the stream while maintaing position. More...
 
- Public Member Functions inherited from Common::ReadStream
byte readByte ()
 Read an unsigned byte from the stream and return it. More...
 
FORCEINLINE int8 readSByte ()
 Read a signed byte from the stream and return it. More...
 
uint16 readUint16LE ()
 Read an unsigned 16-bit word stored in little endian (LSB first) order from the stream and return it. More...
 
uint32 readUint32LE ()
 Read an unsigned 32-bit word stored in little endian (LSB first) order from the stream and return it. More...
 
uint64 readUint64LE ()
 Read an unsigned 64-bit word stored in little endian (LSB first) order from the stream and return it. More...
 
uint16 readUint16BE ()
 Read an unsigned 16-bit word stored in big endian (MSB first) order from the stream and return it. More...
 
uint32 readUint32BE ()
 Read an unsigned 32-bit word stored in big endian (MSB first) order from the stream and return it. More...
 
uint64 readUint64BE ()
 Read an unsigned 64-bit word stored in big endian (MSB first) order from the stream and return it. More...
 
FORCEINLINE int16 readSint16LE ()
 Read a signed 16-bit word stored in little endian (LSB first) order from the stream and return it. More...
 
FORCEINLINE int32 readSint32LE ()
 Read a signed 32-bit word stored in little endian (LSB first) order from the stream and return it. More...
 
FORCEINLINE int64 readSint64LE ()
 Read a signed 64-bit word stored in little endian (LSB first) order from the stream and return it. More...
 
FORCEINLINE int16 readSint16BE ()
 Read a signed 16-bit word stored in big endian (MSB first) order from the stream and return it. More...
 
FORCEINLINE int32 readSint32BE ()
 Read a signed 32-bit word stored in big endian (MSB first) order from the stream and return it. More...
 
FORCEINLINE int64 readSint64BE ()
 Read a signed 64-bit word stored in big endian (MSB first) order from the stream and return it. More...
 
FORCEINLINE float readFloatLE ()
 Read a 32-bit floating point value stored in little endian (LSB first) order from the stream and return it. More...
 
FORCEINLINE float readFloatBE ()
 Read a 32-bit floating point value stored in big endian order from the stream and return it. More...
 
FORCEINLINE double readDoubleLE ()
 Read a 64-bit floating point value stored in little endian (LSB first) order from the stream and return it. More...
 
FORCEINLINE double readDoubleBE ()
 Read a 64-bit floating point value stored in big endian order from the stream and return it. More...
 
SeekableReadStreamreadStream (uint32 dataSize)
 Read the specified amount of data into a malloc'ed buffer which then is wrapped into a MemoryReadStream. More...
 
Common::String readPascalString (bool transformCR=true)
 Read stream in Pascal format, that is, one byte is string length, followed by string data. More...
 
- Public Member Functions inherited from Common::Stream
virtual ~Stream ()
 
- Public Member Functions inherited from Common::NonCopyable
 NonCopyable ()
 

Static Public Member Functions

static bool exists (const String &filename)
 Checks if a given file exists in any of the current default paths, as defined by SearchMan. More...
 

Protected Attributes

SeekableReadStream_handle
 File handle to the actual file; 0 if no file is open. More...
 
String _name
 The name of this file, kept for debugging purposes. More...
 

Detailed Description

TODO: vital to document this core class properly!!! For both users and implementors.

Definition at line 39 of file file.h.

Constructor & Destructor Documentation

◆ File()

Common::File::File ( )

Definition at line 33 of file file.cpp.

◆ ~File()

Common::File::~File ( )
virtual

Reimplemented in Xeen::File.

Definition at line 37 of file file.cpp.

Member Function Documentation

◆ clearErr()

void Common::File::clearErr ( )
virtual

Reset the I/O error status as returned by err().

For a ReadStream, also reset the end-of-stream status returned by eos().

Note
The semantics of any implementation of this method are supposed to match those of ISO C clearerr().

Reimplemented from Common::Stream.

Reimplemented in Scumm::ScummFile.

Definition at line 116 of file file.cpp.

◆ close()

void Common::File::close ( )
virtual

Close the file, if open.

Reimplemented in Scumm::ScummDiskImage, and Scumm::ScummNESFile.

Definition at line 102 of file file.cpp.

◆ eos()

bool Common::File::eos ( ) const
virtual

Returns true if a read failed because the stream end has been reached.

This flag is cleared by clearErr(). For a SeekableReadStream, it is also cleared by a successful seek.

Note
The semantics of any implementation of this method are supposed to match those of ISO C feof(). In particular, in a stream with N bytes, reading exactly N bytes from the start should not set eos; only reading beyond the available data should set it.

Implements Common::ReadStream.

Reimplemented in Scumm::ScummDiskImage, Scumm::ScummNESFile, and Scumm::ScummFile.

Definition at line 121 of file file.cpp.

◆ err()

bool Common::File::err ( ) const
virtual

Returns true if an I/O failure occurred.

This flag is never cleared automatically. In order to clear it, client code has to call clearErr() explicitly.

Note
The semantics of any implementation of this method are supposed to match those of ISO C ferror().

Reimplemented from Common::Stream.

Definition at line 111 of file file.cpp.

◆ exists()

bool Common::File::exists ( const String filename)
static

Checks if a given file exists in any of the current default paths, as defined by SearchMan.

Parameters
filenamethe file to check for
Returns
true if the file exists, false otherwise

Definition at line 90 of file file.cpp.

◆ getName()

const char* Common::File::getName ( ) const
inline

Returns the filename of the opened file for debugging purposes.

Returns
: the filename

Definition at line 118 of file file.h.

◆ isOpen()

bool Common::File::isOpen ( ) const

Checks if the object opened a file successfully.

Returns
: true if any file is opened, false otherwise.

Definition at line 107 of file file.cpp.

◆ open() [1/4]

bool Common::File::open ( const String filename)
virtual

Try to open the file with the given filename, by searching SearchMan.

Note
Must not be called if this file already is open (i.e. if isOpen returns true).
Parameters
filenamethe name of the file to open
Returns
true if file was opened successfully, false otherwise

Reimplemented in Xeen::File, Scumm::ScummSteamFile, Scumm::ScummDiskImage, Scumm::ScummNESFile, Pink::BroFile, Scumm::ScummFile, Pink::OrbFile, Titanic::File, and Scumm::BaseScummFile.

Definition at line 41 of file file.cpp.

◆ open() [2/4]

bool Common::File::open ( const String filename,
Archive archive 
)
virtual

Try to open the file with the given filename from within the given archive.

Note
Must not be called if this file already is open (i.e. if isOpen returns true).
Parameters
filenamethe name of the file to open
archivethe archive in which to search for the file
Returns
true if file was opened successfully, false otherwise

Reimplemented in Xeen::File.

Definition at line 45 of file file.cpp.

◆ open() [3/4]

bool Common::File::open ( const FSNode node)
virtual

Try to open the file corresponding to the give node.

Will check whether the node actually refers to an existing file (and not a directory), and handle those cases gracefully.

Note
Must not be called if this file already is open (i.e. if isOpen returns true).
Parameters
nodethe node to consider.
Returns
true if file was opened successfully, false otherwise

Reimplemented in Xeen::File.

Definition at line 62 of file file.cpp.

◆ open() [4/4]

bool Common::File::open ( SeekableReadStream stream,
const String name 
)
virtual

Try to 'open' the given stream.

That is, we just wrap around it, and if stream is a NULL pointer, we gracefully treat this as if opening failed.

Note
Must not be called if this file already is open (i.e. if isOpen returns true).
Parameters
streama pointer to a SeekableReadStream, or 0
namea string describing the 'file' corresponding to stream
Returns
true if stream was non-zero, false otherwise

Definition at line 77 of file file.cpp.

◆ pos()

int32 Common::File::pos ( ) const
virtual

Obtains the current value of the stream position indicator of the stream.

Returns
the current position indicator, or -1 if an error occurred.

Implements Common::SeekableReadStream.

Reimplemented in Scumm::ScummDiskImage, Scumm::ScummNESFile, Scumm::ScummFile, and Scumm::BaseScummFile.

Definition at line 126 of file file.cpp.

◆ read()

uint32 Common::File::read ( void dataPtr,
uint32  dataSize 
)
virtual

Read data from the stream.

Subclasses must implement this method; all other read methods are implemented using it.

Note
The semantics of any implementation of this method are supposed to match those of ISO C fread(), in particular where it concerns setting error and end of file/stream flags.
Parameters
dataPtrpointer to a buffer into which the data is read
dataSizenumber of bytes to be read
Returns
the number of bytes which were actually read.

Implements Common::ReadStream.

Reimplemented in Scumm::ScummDiskImage, Scumm::ScummNESFile, Scumm::ScummFile, and MutationOfJB::EncryptedFile.

Definition at line 141 of file file.cpp.

◆ seek()

bool Common::File::seek ( int32  offset,
int  whence = SEEK_SET 
)
virtual

Sets the stream position indicator for the stream.

The new position, measured in bytes, is obtained by adding offset bytes to the position specified by whence. If whence is set to SEEK_SET, SEEK_CUR, or SEEK_END, the offset is relative to the start of the file, the current position indicator, or end-of-file, respectively. A successful call to the seek() method clears the end-of-file indicator for the stream.

Note
The semantics of any implementation of this method are supposed to match those of ISO C fseek().
Parameters
offsetthe relative offset in bytes
whencethe seek reference: SEEK_SET, SEEK_CUR, or SEEK_END
Returns
true on success, false in case of a failure

Implements Common::SeekableReadStream.

Reimplemented in Scumm::ScummDiskImage, Scumm::ScummNESFile, Scumm::ScummFile, and Scumm::BaseScummFile.

Definition at line 136 of file file.cpp.

◆ size()

int32 Common::File::size ( ) const
virtual

Obtains the total size of the stream, measured in bytes.

If this value is unknown or can not be computed, -1 is returned.

Returns
the size of the stream, or -1 if an error occurred

Implements Common::SeekableReadStream.

Reimplemented in Scumm::ScummDiskImage, Scumm::ScummNESFile, Scumm::ScummFile, and Scumm::BaseScummFile.

Definition at line 131 of file file.cpp.

Member Data Documentation

◆ _handle

SeekableReadStream* Common::File::_handle
protected

File handle to the actual file; 0 if no file is open.

Definition at line 42 of file file.h.

◆ _name

String Common::File::_name
protected

The name of this file, kept for debugging purposes.

Definition at line 45 of file file.h.


The documentation for this class was generated from the following files: