/* -*- Mode: C++; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
/* ***** BEGIN LICENSE BLOCK *****
* Version: MPL 1.1/GPL 2.0/LGPL 2.1
*
* The contents of this file are subject to the Mozilla Public License Version
* 1.1 (the "License"); you may not use this file except in compliance with
* the License. You may obtain a copy of the License at
*
* Software distributed under the License is distributed on an "AS IS" basis,
* WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
* for the specific language governing rights and limitations under the
* License.
*
* The Original Code is Mozilla FastLoad code.
*
* The Initial Developer of the Original Code is
* Netscape Communications Corporation.
* Portions created by the Initial Developer are Copyright (C) 2001
* the Initial Developer. All Rights Reserved.
*
* Contributor(s):
* Brendan Eich <brendan@mozilla.org> (original author)
*
* Alternatively, the contents of this file may be used under the terms of
* either of the GNU General Public License Version 2 or later (the "GPL"),
* or the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
* in which case the provisions of the GPL or the LGPL are applicable instead
* of those above. If you wish to allow use of your version of this file only
* under the terms of either the GPL or the LGPL, and not to allow others to
* use your version of this file under the terms of the MPL, indicate your
* decision by deleting the provisions above and replace them with the notice
* and other provisions required by the GPL or the LGPL. If you do not delete
* the provisions above, a recipient may use your version of this file under
* the terms of any one of the MPL, the GPL or the LGPL.
*
* ***** END LICENSE BLOCK ***** */
#ifndef nsFastLoadFile_h___
#define nsFastLoadFile_h___
/**
* Mozilla FastLoad file format and helper types.
*/
#include "prtypes.h"
#include "pldhash.h"
#include "nsBinaryStream.h"
#include "nsCOMPtr.h"
#include "nsDebug.h"
#include "nsID.h"
#include "nsMemory.h"
#include "nsVoidArray.h"
#include "nsIFastLoadFileControl.h"
#include "nsIFastLoadService.h"
#include "nsISeekableStream.h"
#include "nsISupportsArray.h"
/**
* FastLoad file Object ID (OID) is an identifier for multiply and cyclicly
* connected objects in the serialized graph of all reachable objects.
*
* Holy Mixed Metaphors: JS, after Common Lisp, uses #n= to define a "sharp
* variable" naming an object that's multiply or cyclicly connected, and #n#
* to stand for a connection to an already-defined object. We too call any
* object with multiple references "sharp", and (here it comes) any object
* with only one reference "dull".
*
* Note that only sharp objects require a mapping from OID to FastLoad file
* offset and other information. Dull objects can be serialized _in situ_
* (where they are referenced) and deserialized when their (singular, shared)
* OID is scanned.
*
* We also compress 16-byte XPCOM IDs into 32-bit dense identifiers to save
* space. See nsFastLoadFooter, below, for the mapping data structure used to
* compute an nsID given an NSFastLoadID.
*/
/**
* A Mozilla FastLoad file is an untagged (in general) stream of objects and
* primitive-type data. Small integers are fairly common, and could easily be
* confused for NSFastLoadIDs and NSFastLoadOIDs. To help catch bugs where
* reader and writer code fail to match, we XOR unlikely 32-bit numbers with
* NSFastLoad*IDs when storing and fetching. The following unlikely values are
* irrational numbers ((sqrt(5)-1)/2, sqrt(2)-1) represented in fixed point.
*
* The reader XORs, converts the ID to an index, and bounds-checks all array
* accesses that use the index. Array access code asserts that the index is in
* bounds, and returns a dummy array element if it isn't.
*/
/**
* An OID can be tagged to introduce the serialized definition of the object,
* or to stand for a strong or weak reference to that object. Thus the high
* 29 bits actually identify the object, and the low three bits tell whether
* the object is being defined or just referenced -- and via what inheritance
* chain or inner object, if necessary.
*
* The MFL_QUERY_INTERFACE_TAG bit helps us cope with aggregation and multiple
* inheritance: object identity follows the XPCOM rule, but a deserializer may
* need to query for an interface not on the primary inheritance chain ending
* in the nsISupports whose address uniquely identifies the XPCOM object being
* referenced or defined.
*/
// NB: do not confuse with nsWeakPtr!
// NB: an NSFastLoadID, not an nsIID!
/**
* The dull object identifier introduces the definition of all objects that
* have only one (necessarily strong) ref in the serialization. The definition
* appears at the point of reference.
*/
/**
* Convert an OID to an index into nsFastLoadFooter::mObjectMap.
*/
/**
* Magic "number" at start of a FastLoad file. Inspired by the PNG "magic"
* string, which inspired XPCOM's typelib (.xpt) file magic. Guaranteed to be
* corrupted by FTP-as-ASCII and other likely errors, meaningful to clued-in
* humans, and ending in ^Z to terminate erroneous text input on Windows.
*/
#define MFL_FILE_VERSION_0 0
/**
* Compute Fletcher's 16-bit checksum over aLength bytes starting at aBuffer,
* with the initial accumulators seeded from *aChecksum, and final checksum
* returned in *aChecksum. The return value is the number of unchecked bytes,
* which may be non-zero if aBuffer is misaligned or aLength is odd. Callers
* should copy any remaining bytes to the front of the next buffer.
*
* If aLastBuffer is false, do not check any bytes remaining due to misaligned
* aBuffer or odd aLength, instead returning the remaining byte count. But if
* aLastBuffer is true, treat aBuffer as the last buffer in the file and check
* every byte, returning 0. Here's a read-loop checksumming sketch:
*
* char buf[BUFSIZE];
* PRUint32 len, rem = 0;
* PRUint32 checksum = 0;
*
* while (NS_SUCCEEDED(rv = Read(buf + rem, sizeof buf - rem, &len)) && len) {
* len += rem;
* rem = NS_AccumulateFastLoadChecksum(&checksum,
* NS_REINTERPRET_CAST(PRUint8*, buf),
* len,
* PR_FALSE);
* if (rem)
* memcpy(buf, buf + len - rem, rem);
* }
*
* if (rem) {
* NS_AccumulateFastLoadChecksum(&checksum,
* NS_REINTERPRET_CAST(PRUint8*, buf),
* rem,
* PR_TRUE);
* }
*
* After this, if NS_SUCCEEDED(rv), checksum contains a valid FastLoad sum.
*/
/**
* Header at the start of a FastLoad file.
*/
struct nsFastLoadHeader {
};
/**
* Footer prefix structure (footer header, ugh), after which come arrays of
* structures or strings counted by these members.
*/
struct nsFastLoadFooterPrefix {
};
struct nsFastLoadSharpObjectInfo {
};
struct nsFastLoadMuxedDocumentInfo {
const char* mURISpec;
};
// forward declarations of opaque types defined in nsFastLoadFile.cpp
struct nsDocumentMapReadEntry;
struct nsDocumentMapWriteEntry;
// So nsFastLoadFileUpdater can verify that its nsIObjectInputStream parameter
// is an nsFastLoadFileReader.
#define NS_FASTLOADFILEREADER_IID \
{0x7d37d1bb,0xcef3,0x4c5f,{0x97,0x68,0x0f,0x89,0x7f,0x1a,0xe1,0x40}}
};
/**
* Inherit from the concrete class nsBinaryInputStream, which inherits from
* abstract nsIObjectInputStream but does not implement its direct methods.
* Though the names are not as clear as I'd like, this seems to be the best
* way to share nsBinaryStream.cpp code.
*/
{
}
}
// nsISupports methods
// overridden nsIObjectInputStream methods
// nsIFastLoadFileControl methods
// nsIFastLoadReadControl methods
// nsISeekableStream methods
// Override Read so we can demultiplex a document interleaved with others.
// Override ReadSegments too, as nsBinaryInputStream::ReadSegments does
// not call through our overridden Read method -- it calls directly into
// the underlying input stream.
/**
* In-memory representation of an indexed nsFastLoadSharpObjectInfo record.
*/
};
/**
* In-memory representation of the FastLoad file footer.
*/
mObjectMap(nsnull) {
}
~nsFastLoadFooter() {
delete[] mObjectMap;
if (mDocumentMap.ops)
}
// These can't be static within GetID and GetSharpObjectEntry or the
// toolchains on HP-UX 10.20's, RH 7.0, and Mac OS X all barf at link
// time ("common symbols not allowed with MY_DHLIB output format", to
// quote the OS X rev of gcc).
return gDummyID;
}
if (index >= mNumSharpObjects)
return gDummySharpObjectEntry;
return mObjectMap[index];
}
// Map from dense, zero-based, uint32 NSFastLoadID to 16-byte nsID.
// Map from dense, zero-based MFL_OID_TO_SHARP_INDEX(oid) to sharp
// object offset and refcnt information.
// Map from URI spec string to nsDocumentMapReadEntry, which helps us
// demultiplex a document's objects from among the interleaved object
// stream segments in the FastLoad file.
// Fast mapping from URI object pointer to mDocumentMap entry, valid
// only while the muxed document is loading.
// List of source filename dependencies that should trigger regeneration
// of the FastLoad file.
};
NS_IMETHOD Close();
};
/**
* Inherit from the concrete class nsBinaryInputStream, which inherits from
* abstract nsIObjectInputStream but does not implement its direct methods.
* Though the names are not as clear as I'd like, this seems to be the best
* way to share nsBinaryStream.cpp code.
*/
{
{
}
{
if (mObjectMap.ops)
if (mDocumentMap.ops)
if (mDependencyMap.ops)
}
// nsISupports methods
// overridden nsIObjectOutputStream methods
// nsIFastLoadFileControl methods
// nsIFastLoadWriteControl methods
// nsISeekableStream methods
NS_IMETHOD Close();
static PLDHashOperator PR_CALLBACK
void *aData);
static PLDHashOperator PR_CALLBACK
void *aData);
static PLDHashOperator PR_CALLBACK
void *aData);
static PLDHashOperator PR_CALLBACK
void *aData);
};
/**
* Subclass of nsFastLoadFileWriter, friend of nsFastLoadFileReader which it
* wraps when a FastLoad file needs to be updated. The wrapped reader can be
* used to demulitplex data for documents already in the FastLoad file, while
* the updater writes new data over the old footer, then writes a new footer
* that maps all data on Close.
*/
{
}
}
// nsISupports methods
// nsIFastLoadFileIO methods
NS_IMETHOD Close();
static PLDHashOperator PR_CALLBACK
void *aData);
};
#endif // nsFastLoadFile_h___