From 3a14549dd7a21496ddf93ba1fcf2eb45418c3eba Mon Sep 17 00:00:00 2001 From: treeform Date: Sun, 21 Dec 2008 19:16:24 +0000 Subject: [PATCH] added some docs as per request http://panda3d.org/phpbb2/viewtopic.php?t=5324 --- panda/src/express/patchfile.cxx | 77 ++++++++++++++++++--------------- 1 file changed, 43 insertions(+), 34 deletions(-) diff --git a/panda/src/express/patchfile.cxx b/panda/src/express/patchfile.cxx index 353f19840e..55d5358dab 100644 --- a/panda/src/express/patchfile.cxx +++ b/panda/src/express/patchfile.cxx @@ -96,7 +96,7 @@ const PN_uint32 Patchfile::_HASH_MASK = (PN_uint32(1) << Patchfile::_HASH_BITS) //////////////////////////////////////////////////////////////////// // Function: Patchfile::Constructor // Access: Public -// Description: +// Description: Create a patch file and initializes internal data //////////////////////////////////////////////////////////////////// Patchfile:: Patchfile() { @@ -108,7 +108,7 @@ Patchfile() { //////////////////////////////////////////////////////////////////// // Function: Patchfile::Constructor // Access: Public -// Description: +// Description: Create patch file with buffer to patch //////////////////////////////////////////////////////////////////// Patchfile:: Patchfile(PT(Buffer) buffer) { @@ -126,7 +126,7 @@ init(PT(Buffer) buffer) { _initiated = false; nassertv(!buffer.is_null()); _buffer = buffer; - + _version_number = 0; _allow_multifile = true; reset_footprint_length(); @@ -150,7 +150,7 @@ Patchfile:: //////////////////////////////////////////////////////////////////// // Function: Patchfile::cleanup // Access: Private -// Description: +// Description: Closes and clean up internal data structures //////////////////////////////////////////////////////////////////// void Patchfile:: cleanup() { @@ -185,7 +185,7 @@ cleanup() { // Function: Patchfile::initiate // Access: Published // Description: Set up to apply the patch to the file (original -// file and patch are destroyed in the process). +// file and patch are destroyed in the process). //////////////////////////////////////////////////////////////////// int Patchfile:: initiate(const Filename &patch_file, const Filename &file) { @@ -264,6 +264,13 @@ read_header(const Filename &patch_file) { // Function: Patchfile::run // Access: Published // Description: Perform one buffer's worth of patching +// Returns EU_ok while patching +// Returns EU_success when done +// If error happens will return one of: +// EU_error_abort : Patching has not been initiated +// EU_error_file_invalid : file is corrupted +// EU_error_invalid_checksum : incompatible patch file +// EU_error_write_file_rename : could not rename file //////////////////////////////////////////////////////////////////// int Patchfile:: run() { @@ -308,7 +315,7 @@ run() { // if there are bytes to add, read them from patch file and write them to output if (express_cat.is_spam() && ADD_length != 0) { express_cat.spam() - << "ADD: " << ADD_length << " (to " + << "ADD: " << ADD_length << " (to " << _write_stream.tellp() << ")" << endl; } @@ -370,7 +377,7 @@ run() { express_cat.spam() << "COPY: " << COPY_length << " bytes from offset " << COPY_offset << " (from " << _origfile_stream.tellg() - << " to " << _write_stream.tellp() << ")" + << " to " << _write_stream.tellp() << ")" << endl; } @@ -396,7 +403,7 @@ run() { if (express_cat.is_debug()) { express_cat.debug() - //<< "result file = " << _result_file_length + //<< "result file = " << _result_file_length << " total bytes = " << _total_bytes_processed << endl; } @@ -480,7 +487,8 @@ run() { //////////////////////////////////////////////////////////////////// // Function: Patchfile::apply // Access: Public -// Description: +// Description: Patches the entire file in one call +// returns true on success and false on error //////////////////////////////////////////////////////////////////// bool Patchfile:: apply(Filename &patch_file, Filename &file) { @@ -541,7 +549,7 @@ internal_read_header(const Filename &patch_file) { if (_version_number >= 1) { // Get the length of the source file. /*PN_uint32 source_file_length =*/ patch_reader.get_uint32(); - + // get the MD5 of the source file. _MD5_ofSource.read_stream(patch_reader); } @@ -697,7 +705,7 @@ calc_match_length(const char* buf1, const char* buf2, PN_uint32 max_length, return 0; } } - + PN_uint32 length = 0; while ((length < max_length) && (*buf1 == *buf2)) { buf1++, buf2++, length++; @@ -824,7 +832,7 @@ emit_COPY(ostream &write_stream, PN_uint32 length, PN_uint32 copy_pos) { // limit. //////////////////////////////////////////////////////////////////// void Patchfile:: -emit_add_and_copy(ostream &write_stream, +emit_add_and_copy(ostream &write_stream, PN_uint32 add_length, const char *add_buffer, PN_uint32 copy_length, PN_uint32 copy_pos) { if (add_length == 0 && copy_length == 0) { @@ -863,7 +871,7 @@ emit_add_and_copy(ostream &write_stream, // emits from consecutive adds or copies. //////////////////////////////////////////////////////////////////// void Patchfile:: -cache_add_and_copy(ostream &write_stream, +cache_add_and_copy(ostream &write_stream, PN_uint32 add_length, const char *add_buffer, PN_uint32 copy_length, PN_uint32 copy_pos) { if (add_length != 0) { @@ -902,7 +910,7 @@ cache_add_and_copy(ostream &write_stream, //////////////////////////////////////////////////////////////////// void Patchfile:: cache_flush(ostream &write_stream) { - emit_add_and_copy(write_stream, + emit_add_and_copy(write_stream, _cache_add_data.size(), _cache_add_data.data(), _cache_copy_length, _cache_copy_start); _cache_add_data = string(); @@ -917,7 +925,7 @@ cache_flush(ostream &write_stream) { // Writes the patchfile header. //////////////////////////////////////////////////////////////////// void Patchfile:: -write_header(ostream &write_stream, +write_header(ostream &write_stream, istream &stream_orig, istream &stream_new) { // prepare to write the patch file header @@ -977,7 +985,7 @@ write_terminator(ostream &write_stream) { // Returns true if successful, false on error. //////////////////////////////////////////////////////////////////// bool Patchfile:: -compute_file_patches(ostream &write_stream, +compute_file_patches(ostream &write_stream, PN_uint32 offset_orig, PN_uint32 offset_new, istream &stream_orig, istream &stream_new) { // read in original file @@ -1050,7 +1058,7 @@ compute_file_patches(ostream &write_stream, int num_skipped = (int)new_pos - (int)start_pos; if (express_cat.is_spam()) { express_cat.spam() - << "build: num_skipped = " << num_skipped + << "build: num_skipped = " << num_skipped << endl; } cache_add_and_copy(write_stream, num_skipped, &buffer_new[start_pos], @@ -1073,7 +1081,7 @@ compute_file_patches(ostream &write_stream, // emit ADD for all remaining bytes PN_uint32 remaining_bytes = result_file_length - start_pos; - cache_add_and_copy(write_stream, remaining_bytes, &buffer_new[start_pos], + cache_add_and_copy(write_stream, remaining_bytes, &buffer_new[start_pos], 0, 0); start_pos += remaining_bytes; } @@ -1096,7 +1104,7 @@ compute_file_patches(ostream &write_stream, // small subfiles. //////////////////////////////////////////////////////////////////// bool Patchfile:: -compute_mf_patches(ostream &write_stream, +compute_mf_patches(ostream &write_stream, PN_uint32 offset_orig, PN_uint32 offset_new, istream &stream_orig, istream &stream_new) { Multifile mf_orig, mf_new; @@ -1161,7 +1169,7 @@ compute_mf_patches(ostream &write_stream, streampos new_start = mf_new.get_subfile_internal_start(ni); size_t new_size = mf_new.get_subfile_internal_length(ni); - if (!patch_subfile(write_stream, offset_orig, offset_new, + if (!patch_subfile(write_stream, offset_orig, offset_new, mf_new.get_subfile_name(ni), stream_origw, orig_start, orig_start + (streampos)orig_size, stream_neww, new_start, new_start + (streampos)new_size)) { @@ -1248,7 +1256,7 @@ read_tar(TarDef &tar, istream &stream) { // previous call to read_tar(). //////////////////////////////////////////////////////////////////// bool Patchfile:: -compute_tar_patches(ostream &write_stream, +compute_tar_patches(ostream &write_stream, PN_uint32 offset_orig, PN_uint32 offset_new, istream &stream_orig, istream &stream_new, TarDef &tar_orig, TarDef &tar_new) { @@ -1299,7 +1307,7 @@ compute_tar_patches(ostream &write_stream, // can accurately detect nested multifiles. The extra data at // the end of the file (possibly introduced by a tar file's // blocking) is the footer, which is also patched separately. - if (!patch_subfile(write_stream, offset_orig, offset_new, "", + if (!patch_subfile(write_stream, offset_orig, offset_new, "", stream_origw, sf_orig._header_start, sf_orig._data_start, stream_neww, sf_new._header_start, sf_new._data_start)) { return false; @@ -1396,6 +1404,7 @@ tar_writefunc(int, const void *, size_t) { // For an original file of size M and a new file of // size N, this algorithm is O(M) in space and // O(M*N) (worst-case) in time. +// return false on error //////////////////////////////////////////////////////////////////// bool Patchfile:: build(Filename file_orig, Filename file_new, Filename patch_name) { @@ -1435,7 +1444,7 @@ build(Filename file_orig, Filename file_new, Filename patch_name) { write_header(write_stream, stream_orig, stream_new); - if (!do_compute_patches(file_orig, file_new, + if (!do_compute_patches(file_orig, file_new, write_stream, 0, 0, stream_orig, stream_new)) { return false; @@ -1469,7 +1478,7 @@ build(Filename file_orig, Filename file_new, Filename patch_name) { //////////////////////////////////////////////////////////////////// bool Patchfile:: do_compute_patches(const Filename &file_orig, const Filename &file_new, - ostream &write_stream, + ostream &write_stream, PN_uint32 offset_orig, PN_uint32 offset_new, istream &stream_orig, istream &stream_new) { nassertr(_add_pos + _cache_add_data.size() + _cache_copy_length == offset_new, false); @@ -1490,7 +1499,7 @@ do_compute_patches(const Filename &file_orig, const Filename &file_new, char *buffer = (char *)PANDA_MALLOC_ARRAY(magic_number.size()); stream_orig.seekg(0, ios::beg); stream_orig.read(buffer, magic_number.size()); - + if (stream_orig.gcount() == (int)magic_number.size() && memcmp(buffer, magic_number.data(), magic_number.size()) == 0) { stream_new.seekg(0, ios::beg); @@ -1546,7 +1555,7 @@ do_compute_patches(const Filename &file_orig, const Filename &file_new, return true; } - + //////////////////////////////////////////////////////////////////// // Function: Patchfile::patch_subfile // Access: Private @@ -1554,7 +1563,7 @@ do_compute_patches(const Filename &file_orig, const Filename &file_new, // Multifile or a tar file. //////////////////////////////////////////////////////////////////// bool Patchfile:: -patch_subfile(ostream &write_stream, +patch_subfile(ostream &write_stream, PN_uint32 offset_orig, PN_uint32 offset_new, const Filename &filename, IStreamWrapper &stream_orig, streampos orig_start, streampos orig_end, @@ -1566,34 +1575,34 @@ patch_subfile(ostream &write_stream, ISubStream subfile_orig(&stream_orig, orig_start, orig_end); ISubStream subfile_new(&stream_new, new_start, new_end); - + bool is_unchanged = false; if (orig_size == new_size) { HashVal hash_orig, hash_new; hash_orig.hash_stream(subfile_orig); hash_new.hash_stream(subfile_new); - + if (hash_orig == hash_new) { // Actually, the subfile is unchanged; just emit it. is_unchanged = true; } } - + if (is_unchanged) { if (express_cat.is_debug() && !filename.empty()) { express_cat.debug() << "Keeping subfile " << filename << "\n"; } - cache_add_and_copy(write_stream, 0, NULL, + cache_add_and_copy(write_stream, 0, NULL, orig_size, offset_orig + orig_start); - + } else { if (!filename.empty()) { express_cat.info() << "Patching subfile " << filename << "\n"; } - - if (!do_compute_patches(filename, filename, write_stream, + + if (!do_compute_patches(filename, filename, write_stream, offset_orig + orig_start, offset_new + new_start, subfile_orig, subfile_new)) { return false;