Panda3D
Classes | Public Member Functions | Static Public Member Functions | Friends | List of all members
Multifile Class Reference

A file that contains a set of files. More...

#include "multifile.h"

Inheritance diagram for Multifile:
ReferenceCount MemoryBase

Public Member Functions

string add_subfile (const string &subfile_name, const Filename &filename, int compression_level)
 Adds a file on disk as a subfile to the Multifile. More...
 
string add_subfile (const string &subfile_name, istream *subfile_data, int compression_level)
 Adds a file from a stream as a subfile to the Multifile. More...
 
void close ()
 Closes the Multifile if it is open. More...
 
bool compare_subfile (int index, const Filename &filename)
 Performs a byte-for-byte comparison of the indicated file on disk with the nth subfile. More...
 
bool extract_subfile (int index, const Filename &filename)
 Extracts the nth subfile into a file with the given name. More...
 
bool extract_subfile_to (int index, ostream &out)
 Extracts the nth subfile to the indicated ostream. More...
 
int find_subfile (const string &subfile_name) const
 Returns the index of the subfile with the indicated name, or -1 if the named subfile is not within the Multifile. More...
 
bool flush ()
 Writes all contents of the Multifile to disk. More...
 
const string & get_encryption_algorithm () const
 Returns the encryption algorithm that was specified by set_encryption_algorithm(). More...
 
bool get_encryption_flag () const
 Returns the flag indicating whether subsequently-added subfiles should be encrypted before writing them to the multifile. More...
 
int get_encryption_iteration_count () const
 Returns the value that was specified by set_encryption_iteration_count(). More...
 
int get_encryption_key_length () const
 Returns the encryption key length, in bits, that was specified by set_encryption_key_length(). More...
 
const string & get_encryption_password () const
 Returns the password that will be used to encrypt subfiles subsequently added to the multifile. More...
 
const string & get_header_prefix () const
 Returns the string that preceded the Multifile header on the file, if any. More...
 
streampos get_index_end () const
 Returns the first byte that is guaranteed to follow any index byte already written to disk in the Multifile. More...
 
const Filenameget_multifile_name () const
 Returns the filename of the Multifile, if it is available. More...
 
int get_num_subfiles () const
 Returns the number of subfiles within the Multifile. More...
 
bool get_record_timestamp () const
 Returns the flag indicating whether timestamps should be recorded within the Multifile or not. More...
 
size_t get_scale_factor () const
 Returns the internal scale factor for this Multifile. More...
 
size_t get_subfile_internal_length (int index) const
 Returns the number of bytes the indicated subfile consumes within the archive. More...
 
streampos get_subfile_internal_start (int index) const
 Returns the starting byte position within the Multifile at which the indicated subfile begins. More...
 
size_t get_subfile_length (int index) const
 Returns the uncompressed data length of the nth subfile. More...
 
const string & get_subfile_name (int index) const
 Returns the name of the nth subfile. More...
 
time_t get_subfile_timestamp (int index) const
 Returns the modification time of the nth subfile. More...
 
time_t get_timestamp () const
 Returns the modification timestamp of the overall Multifile. More...
 
bool has_directory (const string &subfile_name) const
 Returns true if the indicated subfile name is the directory prefix to one or more files within the Multifile. More...
 
bool is_read_valid () const
 Returns true if the Multifile has been opened for read mode and there have been no errors, and individual Subfile contents may be extracted. More...
 
bool is_subfile_compressed (int index) const
 Returns true if the indicated subfile has been compressed when stored within the archive, false otherwise. More...
 
bool is_subfile_encrypted (int index) const
 Returns true if the indicated subfile has been encrypted when stored within the archive, false otherwise. More...
 
bool is_subfile_text (int index) const
 Returns true if the indicated subfile represents text data, or false if it represents binary data. More...
 
bool is_write_valid () const
 Returns true if the Multifile has been opened for write mode and there have been no errors, and Subfiles may be added or removed from the Multifile. More...
 
void ls (ostream &out=cout) const
 Shows a list of all subfiles within the Multifile. More...
 
 MAKE_SEQ (get_subfile_names, get_num_subfiles, get_subfile_name)
 
bool needs_repack () const
 Returns true if the Multifile index is suboptimal and should be repacked. More...
 
bool open_read (const Filename &multifile_name, const streampos &offset=0)
 Opens the named Multifile on disk for reading. More...
 
bool open_read (IStreamWrapper *multifile_stream, bool owns_pointer=false, const streampos &offset=0)
 Opens an anonymous Multifile for reading using an istream. More...
 
istream * open_read_subfile (int index)
 Returns an istream that may be used to read the indicated subfile. More...
 
bool open_read_write (const Filename &multifile_name)
 Opens the named Multifile on disk for reading and writing. More...
 
bool open_read_write (iostream *multifile_stream, bool owns_pointer=false)
 Opens an anonymous Multifile for reading and writing using an iostream. More...
 
bool open_write (const Filename &multifile_name)
 Opens the named Multifile on disk for writing. More...
 
bool open_write (ostream *multifile_stream, bool owns_pointer=false)
 Opens an anonymous Multifile for writing using an ostream. More...
 
void output (ostream &out) const
 
string read_subfile (int index)
 Returns a string that contains the entire contents of the indicated subfile. More...
 
bool read_subfile (int index, string &result)
 Fills a string with the entire contents of the indicated subfile. More...
 
bool read_subfile (int index, pvector< unsigned char > &result)
 Fills a pvector with the entire contents of the indicated subfile. More...
 
void remove_subfile (int index)
 Removes the nth subfile from the Multifile. More...
 
bool remove_subfile (const string &subfile_name)
 Removes the named subfile from the Multifile, if it exists; returns true if successfully removed, or false if it did not exist in the first place. More...
 
bool repack ()
 Forces a complete rewrite of the Multifile and all of its contents, so that its index will appear at the beginning of the file with all of the subfiles listed in alphabetical order. More...
 
bool scan_directory (vector_string &contents, const string &subfile_name) const
 Considers subfile_name to be the name of a subdirectory within the Multifile, but not a file itself; fills the given vector up with the sorted list of subdirectories or files within the named directory. More...
 
void set_encryption_algorithm (const string &encryption_algorithm)
 Specifies the encryption algorithm that should be used for future calls to add_subfile(). More...
 
void set_encryption_flag (bool flag)
 Sets the flag indicating whether subsequently-added subfiles should be encrypted before writing them to the multifile. More...
 
void set_encryption_iteration_count (int encryption_iteration_count)
 Specifies the number of times to repeatedly hash the key before writing it to the stream in future calls to add_subfile(). More...
 
void set_encryption_key_length (int encryption_key_length)
 Specifies the length of the key, in bits, that should be used to encrypt the stream in future calls to add_subfile(). More...
 
void set_encryption_password (const string &encryption_password)
 Specifies the password that will be used to encrypt subfiles subsequently added to the multifile, if the encryption flag is also set true (see set_encryption_flag()). More...
 
void set_header_prefix (const string &header_prefix)
 Sets the string which is written to the Multifile before the Multifile header. More...
 
void set_multifile_name (const Filename &multifile_name)
 Replaces the filename of the Multifile. More...
 
void set_record_timestamp (bool record_timestamp)
 Sets the flag indicating whether timestamps should be recorded within the Multifile or not. More...
 
void set_scale_factor (size_t scale_factor)
 Changes the internal scale factor for this Multifile. More...
 
string update_subfile (const string &subfile_name, const Filename &filename, int compression_level)
 Adds a file on disk to the subfile. More...
 
- Public Member Functions inherited from ReferenceCount
int get_ref_count () const
 Returns the current reference count. More...
 
WeakReferenceListget_weak_list () const
 Returns the WeakReferenceList associated with this ReferenceCount object. More...
 
bool has_weak_list () const
 Returns true if this particular ReferenceCount object has a WeakReferenceList created, false otherwise. More...
 
void local_object ()
 This function should be called, once, immediately after creating a new instance of some ReferenceCount-derived object on the stack. More...
 
void ref () const
 Explicitly increments the reference count. More...
 
bool test_ref_count_integrity () const
 Does some easy checks to make sure that the reference count isn't completely bogus. More...
 
bool test_ref_count_nonzero () const
 Does some easy checks to make sure that the reference count isn't zero, or completely bogus. More...
 
virtual bool unref () const
 Explicitly decrements the reference count. More...
 
void weak_ref (WeakPointerToVoid *ptv)
 Adds the indicated PointerToVoid as a weak reference to this object. More...
 
void weak_unref (WeakPointerToVoid *ptv)
 Removes the indicated PointerToVoid as a weak reference to this object. More...
 

Static Public Member Functions

static void close_read_subfile (istream *stream)
 Closes a file opened by a previous call to open_read_subfile(). More...
 
static string get_magic_number ()
 Returns a string with the first n bytes written to a Multifile, to identify it as a Multifile. More...
 
- Static Public Member Functions inherited from ReferenceCount
static TypeHandle get_class_type ()
 
static void init_type ()
 

Friends

class Subfile
 

Detailed Description

A file that contains a set of files.

Definition at line 34 of file multifile.h.

Member Function Documentation

◆ add_subfile() [1/2]

string Multifile::add_subfile ( const string &  subfile_name,
const Filename filename,
int  compression_level 
)

Adds a file on disk as a subfile to the Multifile.

The file named by filename will be read and added to the Multifile at the next call to flush(). If there already exists a subfile with the indicated name, it is replaced without examining its contents (but see also update_subfile).

Filename::set_binary() or set_text() must have been called previously to specify the nature of the source file. If set_text() was called, the text flag will be set on the subfile.

Returns the subfile name on success (it might have been modified slightly), or empty string on failure.

Definition at line 480 of file multifile.cxx.

References Filename::exists(), Filename::is_binary_or_text(), Filename::is_text(), and Filename::set_binary().

Referenced by set_scale_factor().

◆ add_subfile() [2/2]

string Multifile::add_subfile ( const string &  subfile_name,
istream *  subfile_data,
int  compression_level 
)

Adds a file from a stream as a subfile to the Multifile.

The indicated istream will be read and its contents added to the Multifile at the next call to flush(). The file will be added as a binary subfile.

Note that the istream must remain untouched and unused by any other code until flush() is called. At that time, the Multifile will read the entire contents of the istream from the current file position to the end of the file. Subsequently, the Multifile will *not* close or delete the istream. It is the caller's responsibility to ensure that the istream pointer does not destruct during the lifetime of the Multifile.

Returns the subfile name on success (it might have been modified slightly), or empty string on failure.

Definition at line 534 of file multifile.cxx.

References update_subfile().

◆ close()

void Multifile::close ( )

Closes the Multifile if it is open.

All changes are flushed to disk, and the file becomes invalid for further operations until the next call to open().

Definition at line 376 of file multifile.cxx.

References set_scale_factor().

Referenced by open_read_write().

◆ close_read_subfile()

void Multifile::close_read_subfile ( istream *  stream)
static

Closes a file opened by a previous call to open_read_subfile().

This really just deletes the istream pointer, but it is recommended to use this interface instead of deleting it explicitly, to help work around compiler issues.

Definition at line 1876 of file multifile.cxx.

References extract_subfile().

Referenced by open_read_subfile(), Extractor::reset(), and Extractor::step().

◆ compare_subfile()

bool Multifile::compare_subfile ( int  index,
const Filename filename 
)

Performs a byte-for-byte comparison of the indicated file on disk with the nth subfile.

Returns true if the files are equivalent, or false if they are different (or the file is missing).

If Filename::set_binary() or set_text() has already been called, it specifies the nature of the source file. If this is different from the text flag of the subfile, the comparison will always return false. If this has not been specified, it will be set from the text flag of the subfile.

Definition at line 1976 of file multifile.cxx.

References Filename::exists(), Filename::is_binary(), Filename::is_text(), ls(), Filename::open_read(), Filename::set_binary(), and Filename::set_text().

Referenced by extract_subfile_to().

◆ extract_subfile()

bool Multifile::extract_subfile ( int  index,
const Filename filename 
)

Extracts the nth subfile into a file with the given name.

Definition at line 1898 of file multifile.cxx.

References extract_subfile_to(), and Filename::set_binary().

Referenced by close_read_subfile().

◆ extract_subfile_to()

bool Multifile::extract_subfile_to ( int  index,
ostream &  out 
)

Extracts the nth subfile to the indicated ostream.

Definition at line 1933 of file multifile.cxx.

References compare_subfile().

Referenced by extract_subfile().

◆ find_subfile()

int Multifile::find_subfile ( const string &  subfile_name) const

Returns the index of the subfile with the indicated name, or -1 if the named subfile is not within the Multifile.

Definition at line 1561 of file multifile.cxx.

References has_directory().

Referenced by get_num_subfiles(), and remove_subfile().

◆ flush()

bool Multifile::flush ( void  )

Writes all contents of the Multifile to disk.

Until flush() is called, add_subfile() and remove_subfile() do not actually do anything to disk. At this point, all of the recently-added subfiles are read and their contents are added to the end of the Multifile, and the recently-removed subfiles are marked gone from the Multifile.

This may result in a suboptimal index. To guarantee that the index is written at the beginning of the file, call repack() instead of flush().

It is not necessary to call flush() explicitly unless you are concerned about reading the recently-added subfiles immediately.

Returns true on success, false on failure.

Definition at line 1309 of file multifile.cxx.

References StreamWriter::add_uint32(), and repack().

Referenced by set_encryption_algorithm(), set_encryption_iteration_count(), set_encryption_key_length(), set_encryption_password(), and update_subfile().

◆ get_encryption_algorithm()

const string & Multifile::get_encryption_algorithm ( ) const
inline

Returns the encryption algorithm that was specified by set_encryption_algorithm().

Definition at line 248 of file multifile.I.

References set_encryption_key_length().

Referenced by set_encryption_algorithm().

◆ get_encryption_flag()

bool Multifile::get_encryption_flag ( ) const
inline

Returns the flag indicating whether subsequently-added subfiles should be encrypted before writing them to the multifile.

See set_encryption_flag().

Definition at line 172 of file multifile.I.

References set_encryption_password().

Referenced by set_encryption_flag().

◆ get_encryption_iteration_count()

int Multifile::get_encryption_iteration_count ( ) const
inline

Returns the value that was specified by set_encryption_iteration_count().

Definition at line 327 of file multifile.I.

References remove_subfile().

Referenced by set_encryption_iteration_count().

◆ get_encryption_key_length()

int Multifile::get_encryption_key_length ( ) const
inline

Returns the encryption key length, in bits, that was specified by set_encryption_key_length().

Definition at line 287 of file multifile.I.

References set_encryption_iteration_count().

Referenced by set_encryption_key_length().

◆ get_encryption_password()

const string & Multifile::get_encryption_password ( ) const
inline

Returns the password that will be used to encrypt subfiles subsequently added to the multifile.

See set_encryption_password().

Definition at line 207 of file multifile.I.

References set_encryption_algorithm().

Referenced by set_encryption_password().

◆ get_header_prefix()

const string & Multifile::get_header_prefix ( ) const
inline

Returns the string that preceded the Multifile header on the file, if any.

See set_header_prefix().

Definition at line 387 of file multifile.I.

Referenced by get_magic_number().

◆ get_index_end()

streampos Multifile::get_index_end ( ) const

Returns the first byte that is guaranteed to follow any index byte already written to disk in the Multifile.

This number is largely meaningless in many cases, but if needs_repack() is false, and the file is flushed, this will indicate the number of bytes in the header + index. Everything at this byte position and later will be actual data.

Definition at line 1785 of file multifile.cxx.

References get_subfile_internal_start().

Referenced by is_subfile_text().

◆ get_magic_number()

string Multifile::get_magic_number ( )
inlinestatic

Returns a string with the first n bytes written to a Multifile, to identify it as a Multifile.

Definition at line 376 of file multifile.I.

References get_header_prefix().

Referenced by read_subfile().

◆ get_multifile_name()

const Filename & Multifile::get_multifile_name ( ) const
inline

Returns the filename of the Multifile, if it is available.

Definition at line 23 of file multifile.I.

References set_multifile_name().

Referenced by VirtualFileSystem::unmount().

◆ get_num_subfiles()

int Multifile::get_num_subfiles ( ) const

Returns the number of subfiles within the Multifile.

The subfiles may be accessed in alphabetical order by iterating through [0 .. get_num_subfiles()).

Definition at line 1549 of file multifile.cxx.

References find_subfile().

Referenced by repack().

◆ get_record_timestamp()

bool Multifile::get_record_timestamp ( ) const
inline

Returns the flag indicating whether timestamps should be recorded within the Multifile or not.

See set_record_timestamp().

Definition at line 121 of file multifile.I.

References get_scale_factor().

Referenced by set_record_timestamp().

◆ get_scale_factor()

size_t Multifile::get_scale_factor ( ) const
inline

Returns the internal scale factor for this Multifile.

See set_scale_factor().

Definition at line 132 of file multifile.I.

References set_encryption_flag().

Referenced by get_record_timestamp().

◆ get_subfile_internal_length()

size_t Multifile::get_subfile_internal_length ( int  index) const

Returns the number of bytes the indicated subfile consumes within the archive.

For compressed subfiles, this will generally be smaller than get_subfile_length(); for encrypted (but noncompressed) subfiles, it may be slightly different, for noncompressed and nonencrypted subfiles, it will be equal.

Definition at line 1818 of file multifile.cxx.

References open_read_subfile().

Referenced by get_subfile_internal_start().

◆ get_subfile_internal_start()

streampos Multifile::get_subfile_internal_start ( int  index) const

Returns the starting byte position within the Multifile at which the indicated subfile begins.

This may be used, with get_subfile_internal_length(), for low-level access to the subfile, but usually it is better to use open_read_subfile() instead (which automatically decrypts and/or uncompresses the subfile data).

Definition at line 1801 of file multifile.cxx.

References get_subfile_internal_length().

Referenced by get_index_end().

◆ get_subfile_length()

size_t Multifile::get_subfile_length ( int  index) const

Returns the uncompressed data length of the nth subfile.

This might return 0 if the subfile has recently been added and flush() has not yet been called.

Definition at line 1703 of file multifile.cxx.

References get_subfile_timestamp().

Referenced by get_subfile_name().

◆ get_subfile_name()

const string & Multifile::get_subfile_name ( int  index) const

Returns the name of the nth subfile.

Definition at line 1686 of file multifile.cxx.

References get_subfile_length().

Referenced by remove_subfile().

◆ get_subfile_timestamp()

time_t Multifile::get_subfile_timestamp ( int  index) const

Returns the modification time of the nth subfile.

If this is called on an older .mf file, which did not store individual timestamps in the file (or if get_record_timestamp() is false), this will return the modification time of the overall multifile.

Definition at line 1719 of file multifile.cxx.

References is_subfile_compressed().

Referenced by get_subfile_length().

◆ get_timestamp()

time_t Multifile::get_timestamp ( ) const
inline

Returns the modification timestamp of the overall Multifile.

This indicates the most recent date at which subfiles were added or removed from the Multifile. Note that it is logically possible for an individual subfile to have a more recent timestamp than the overall timestamp.

Definition at line 86 of file multifile.I.

References set_record_timestamp().

Referenced by needs_repack(), and read_subfile().

◆ has_directory()

bool Multifile::has_directory ( const string &  subfile_name) const

Returns true if the indicated subfile name is the directory prefix to one or more files within the Multifile.

That is, the Multifile contains at least one file named "subfile_name/...".

Definition at line 1582 of file multifile.cxx.

References scan_directory().

Referenced by find_subfile().

◆ is_read_valid()

bool Multifile::is_read_valid ( ) const
inline

Returns true if the Multifile has been opened for read mode and there have been no errors, and individual Subfile contents may be extracted.

Definition at line 48 of file multifile.I.

References is_write_valid().

Referenced by set_multifile_name().

◆ is_subfile_compressed()

bool Multifile::is_subfile_compressed ( int  index) const

Returns true if the indicated subfile has been compressed when stored within the archive, false otherwise.

Definition at line 1736 of file multifile.cxx.

References is_subfile_encrypted().

Referenced by get_subfile_timestamp().

◆ is_subfile_encrypted()

bool Multifile::is_subfile_encrypted ( int  index) const

Returns true if the indicated subfile has been encrypted when stored within the archive, false otherwise.

Definition at line 1749 of file multifile.cxx.

References is_subfile_text().

Referenced by is_subfile_compressed().

◆ is_subfile_text()

bool Multifile::is_subfile_text ( int  index) const

Returns true if the indicated subfile represents text data, or false if it represents binary data.

If the file is text data, it may have been processed by end-of-line conversion when it was added. (But the actual bits in the multifile will represent the standard Unix end-of-line convention, e.g.
instead of
.)

Definition at line 1766 of file multifile.cxx.

References get_index_end().

Referenced by is_subfile_encrypted().

◆ is_write_valid()

bool Multifile::is_write_valid ( ) const
inline

Returns true if the Multifile has been opened for write mode and there have been no errors, and Subfiles may be added or removed from the Multifile.

Definition at line 60 of file multifile.I.

References needs_repack().

Referenced by is_read_valid().

◆ ls()

void Multifile::ls ( ostream &  out = cout) const

Shows a list of all subfiles within the Multifile.

Definition at line 2083 of file multifile.cxx.

References set_header_prefix().

Referenced by compare_subfile().

◆ needs_repack()

bool Multifile::needs_repack ( ) const
inline

Returns true if the Multifile index is suboptimal and should be repacked.

Call repack() to achieve this.

Definition at line 71 of file multifile.I.

References get_timestamp().

Referenced by is_write_valid().

◆ open_read() [1/2]

bool Multifile::open_read ( const Filename multifile_name,
const streampos &  offset = 0 
)

Opens the named Multifile on disk for reading.

The Multifile index is read in, and the list of subfiles becomes available; individual subfiles may then be extracted or read, but the list of subfiles may not be modified.

Also see the version of open_read() which accepts an istream. Returns true on success, false on failure.

Definition at line 190 of file multifile.cxx.

References VirtualFileSystem::get_file(), VirtualFileSystem::get_global_ptr(), and Filename::set_binary().

◆ open_read() [2/2]

bool Multifile::open_read ( IStreamWrapper multifile_stream,
bool  owns_pointer = false,
const streampos &  offset = 0 
)

Opens an anonymous Multifile for reading using an istream.

There must be seek functionality via seekg() and tellg() on the istream.

If owns_pointer is true, then the Multifile assumes ownership of the stream pointer and will delete it when the multifile is closed, including if this function returns false.

Definition at line 227 of file multifile.cxx.

References open_write().

◆ open_read_subfile()

istream * Multifile::open_read_subfile ( int  index)

Returns an istream that may be used to read the indicated subfile.

You may seek() within this istream to your heart's content; even though it will be a reference to the already-opened pfstream of the Multifile itself, byte 0 appears to be the beginning of the subfile and EOF appears to be the end of the subfile.

The returned istream will have been allocated via new; you should pass the pointer to close_read_subfile() when you are finished with it to delete it and release its resources.

Any future calls to repack() or close() (or the Multifile destructor) will invalidate all currently open subfile pointers.

The return value will be NULL if the stream cannot be opened for some reason.

Definition at line 1847 of file multifile.cxx.

References close_read_subfile().

Referenced by get_subfile_internal_length(), and read_subfile().

◆ open_read_write() [1/2]

bool Multifile::open_read_write ( const Filename multifile_name)

Opens the named Multifile on disk for reading and writing.

If there already exists a file by that name, its index is read. Subfiles may be added or removed, and the resulting changes will be written to the named file.

Also see the version of open_read_write() which accepts an iostream. Returns true on success, false on failure.

Definition at line 303 of file multifile.cxx.

References Filename::exists(), Filename::get_timestamp(), Filename::open_read_write(), and Filename::set_binary().

Referenced by open_write().

◆ open_read_write() [2/2]

bool Multifile::open_read_write ( iostream *  multifile_stream,
bool  owns_pointer = false 
)

Opens an anonymous Multifile for reading and writing using an iostream.

There must be seek functionality via seekg()/seekp() and tellg()/tellp() on the iostream.

If owns_pointer is true, then the Multifile assumes ownership of the stream pointer and will delete it when the multifile is closed, including if this function returns false.

Definition at line 342 of file multifile.cxx.

References close().

◆ open_write() [1/2]

bool Multifile::open_write ( const Filename multifile_name)

Opens the named Multifile on disk for writing.

If there already exists a file by that name, it is truncated. The Multifile is then prepared for accepting a brand new set of subfiles, which will be written to the indicated filename. Individual subfiles may not be extracted or read.

Also see the version of open_write() which accepts an ostream. Returns true on success, false on failure.

Definition at line 252 of file multifile.cxx.

References Filename::open_write(), and Filename::set_binary().

Referenced by open_read().

◆ open_write() [2/2]

bool Multifile::open_write ( ostream *  multifile_stream,
bool  owns_pointer = false 
)

Opens an anonymous Multifile for writing using an ostream.

There must be seek functionality via seekp() and tellp() on the pstream.

If owns_pointer is true, then the Multifile assumes ownership of the stream pointer and will delete it when the multifile is closed, including if this function returns false.

Definition at line 279 of file multifile.cxx.

References open_read_write().

◆ read_subfile() [1/3]

string Multifile::read_subfile ( int  index)
inline

Returns a string that contains the entire contents of the indicated subfile.

Definition at line 363 of file multifile.I.

References get_magic_number().

Referenced by read_subfile(), remove_subfile(), and set_header_prefix().

◆ read_subfile() [2/3]

bool Multifile::read_subfile ( int  index,
string &  result 
)

Fills a string with the entire contents of the indicated subfile.

Definition at line 2149 of file multifile.cxx.

References read_subfile().

◆ read_subfile() [3/3]

bool Multifile::read_subfile ( int  index,
pvector< unsigned char > &  result 
)

◆ remove_subfile() [1/2]

void Multifile::remove_subfile ( int  index)

Removes the nth subfile from the Multifile.

This will cause all subsequent index numbers to decrease by one. The file will not actually be removed from the disk until the next call to flush().

Note that this does not actually remove the data from the indicated subfile; it simply removes it from the index. The Multifile will not be reduced in size after this operation, until the next call to repack().

Definition at line 1666 of file multifile.cxx.

References get_subfile_name().

Referenced by get_encryption_iteration_count(), remove_subfile(), and scan_directory().

◆ remove_subfile() [2/2]

bool Multifile::remove_subfile ( const string &  subfile_name)
inline

Removes the named subfile from the Multifile, if it exists; returns true if successfully removed, or false if it did not exist in the first place.

The file will not actually be removed from the disk until the next call to flush().

Note that this does not actually remove the data from the indicated subfile; it simply removes it from the index. The Multifile will not be reduced in size after this operation, until the next call to repack().

Definition at line 347 of file multifile.I.

References find_subfile(), read_subfile(), and remove_subfile().

◆ repack()

bool Multifile::repack ( )

Forces a complete rewrite of the Multifile and all of its contents, so that its index will appear at the beginning of the file with all of the subfiles listed in alphabetical order.

This is considered optimal for reading, and is the standard configuration; but it is not essential to do this.

It is only valid to call this if the Multifile was opened using open_read_write() and an explicit filename, rather than an iostream. Also, we must have write permission to the directory containing the Multifile.

Returns true on success, false on failure.

Definition at line 1470 of file multifile.cxx.

References Filename::get_dirname(), get_num_subfiles(), Filename::open_write(), Filename::rename_to(), Filename::set_binary(), Filename::temporary(), and Filename::unlink().

Referenced by flush().

◆ scan_directory()

bool Multifile::scan_directory ( vector_string &  contents,
const string &  subfile_name 
) const

Considers subfile_name to be the name of a subdirectory within the Multifile, but not a file itself; fills the given vector up with the sorted list of subdirectories or files within the named directory.

Note that directories do not exist explicitly within a Multifile; this just checks for the existence of files with the given initial prefix.

Returns true if successful, false otherwise.

Definition at line 1619 of file multifile.cxx.

References remove_subfile().

Referenced by has_directory().

◆ set_encryption_algorithm()

void Multifile::set_encryption_algorithm ( const string &  encryption_algorithm)
inline

Specifies the encryption algorithm that should be used for future calls to add_subfile().

The default is whatever is specified by the encryption-algorithm config variable. The complete set of available algorithms is defined by the current version of OpenSSL.

If an invalid algorithm is specified, there is no immediate error return code, but flush() will fail and the file will be invalid.

It is possible to apply a different encryption algorithm to different files, and unlike the password, this does not interfere with mounting the multifile via VFS. Changing this value may cause an implicit call to flush().

Definition at line 232 of file multifile.I.

References flush(), and get_encryption_algorithm().

Referenced by get_encryption_password().

◆ set_encryption_flag()

void Multifile::set_encryption_flag ( bool  flag)
inline

Sets the flag indicating whether subsequently-added subfiles should be encrypted before writing them to the multifile.

If true, subfiles will be encrypted; if false (the default), they will be written without encryption.

When true, subfiles will be encrypted with the password specified by set_encryption_password(). It is possible to apply a different password to different files, but the resulting file can't be mounted via VFS.

Definition at line 152 of file multifile.I.

References get_encryption_flag().

Referenced by get_scale_factor().

◆ set_encryption_iteration_count()

void Multifile::set_encryption_iteration_count ( int  encryption_iteration_count)
inline

Specifies the number of times to repeatedly hash the key before writing it to the stream in future calls to add_subfile().

Its purpose is to make it computationally more expensive for an attacker to search the key space exhaustively. This should be a multiple of 1,000 and should not exceed about 65 million; the value 0 indicates just one application of the hashing algorithm.

The default is whatever is specified by the multifile-encryption-iteration-count config variable.

It is possible to apply a different iteration count to different files, and unlike the password, this does not interfere with mounting the multifile via VFS. Changing this value causes an implicit call to flush().

Definition at line 313 of file multifile.I.

References flush(), and get_encryption_iteration_count().

Referenced by get_encryption_key_length().

◆ set_encryption_key_length()

void Multifile::set_encryption_key_length ( int  encryption_key_length)
inline

Specifies the length of the key, in bits, that should be used to encrypt the stream in future calls to add_subfile().

The default is whatever is specified by the encryption-key-length config variable.

If an invalid key_length for the chosen algorithm is specified, there is no immediate error return code, but flush() will fail and the file will be invalid.

It is possible to apply a different key length to different files, and unlike the password, this does not interfere with mounting the multifile via VFS. Changing this value may cause an implicit call to flush().

Definition at line 271 of file multifile.I.

References flush(), and get_encryption_key_length().

Referenced by get_encryption_algorithm().

◆ set_encryption_password()

void Multifile::set_encryption_password ( const string &  encryption_password)
inline

Specifies the password that will be used to encrypt subfiles subsequently added to the multifile, if the encryption flag is also set true (see set_encryption_flag()).

It is possible to apply a different password to different files, but the resulting file can't be mounted via VFS. Changing this value may cause an implicit call to flush().

Definition at line 190 of file multifile.I.

References flush(), and get_encryption_password().

Referenced by get_encryption_flag(), VirtualFileSystem::mount(), and VirtualFileSystem::mount_loop().

◆ set_header_prefix()

void Multifile::set_header_prefix ( const string &  header_prefix)

Sets the string which is written to the Multifile before the Multifile header.

This string must begin with a hash mark and end with a newline character; and if it includes embedded newline characters, each one must be followed by a hash mark. If these conditions are not initially true, the string will be modified as necessary to make it so.

This is primarily useful as a simple hack to allow p3d applications to be run directly from the command line on Unix-like systems.

The return value is true if successful, or false on failure (for instance, because the header prefix violates the above rules).

Definition at line 2111 of file multifile.cxx.

References read_subfile().

Referenced by ls().

◆ set_multifile_name()

void Multifile::set_multifile_name ( const Filename multifile_name)
inline

Replaces the filename of the Multifile.

This is primarily used for documentation purposes only; changing this name does not open the indicated file. See open_read() or open_write() for that.

Definition at line 36 of file multifile.I.

References is_read_valid().

Referenced by get_multifile_name().

◆ set_record_timestamp()

void Multifile::set_record_timestamp ( bool  flag)
inline

Sets the flag indicating whether timestamps should be recorded within the Multifile or not.

The default is true, indicating the Multifile will record timestamps for the overall file and also for each subfile.

If this is false, the Multifile will not record timestamps internally. In this case, the return value from get_timestamp() or get_subfile_timestamp() will be estimations.

You may want to set this false to minimize the bitwise difference between independently-generated Multifiles.

Definition at line 108 of file multifile.I.

References get_record_timestamp().

Referenced by get_timestamp().

◆ set_scale_factor()

void Multifile::set_scale_factor ( size_t  scale_factor)

Changes the internal scale factor for this Multifile.

This is normally 1, but it may be set to any arbitrary value (greater than zero) to support Multifile archives that exceed 4GB, if necessary. (Individual subfiles may still not exceed 4GB.)

All addresses within the file are rounded up to the next multiple of _scale_factor, and zeros are written to the file to fill the resulting gaps. Then the address is divided by _scale_factor and written out as a 32-bit integer. Thus, setting a scale factor of 2 supports up to 8GB files, 3 supports 12GB files, etc.

Calling this function on an already-existing Multifile will have no immediate effect until a future call to repack() or close() (or until the Multifile is destructed).

Definition at line 442 of file multifile.cxx.

References add_subfile().

Referenced by close().

◆ update_subfile()

string Multifile::update_subfile ( const string &  subfile_name,
const Filename filename,
int  compression_level 
)

Adds a file on disk to the subfile.

If a subfile already exists with the same name, its contents are compared byte-for-byte to the disk file, and it is replaced only if it is different; otherwise, the multifile is left unchanged.

Filename::set_binary() or set_text() must have been called previously to specify the nature of the source file. If set_text() was called, the text flag will be set on the subfile.

Definition at line 564 of file multifile.cxx.

References StreamWriter::add_uint32(), StreamWriter::append_data(), Filename::exists(), flush(), VirtualFileSystem::get_global_ptr(), Filename::is_binary_or_text(), Filename::is_text(), and Filename::set_binary().

Referenced by add_subfile().


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