Binary Document Object Model classes

Binary Document Object Model (DOM) represents binary document as a tree of objects. This tree matches internal document structure.
Binary file and stream gets parsed and validated automatically using Schema Object Model (SOM) classes and top-level classes.
Binary DOM classes allow you to load documents and document fragments, validate them, create, modify and save save back Binary DOM to a file or stream.
Technically, DOM is a class hierarchy based on BinNode class which defines all the basic node functionality.
Here is the list of derived classes:
  • BinValue - represents a single value of primitive type. Always stored in memory.
  • BinValueArray - represents an array of primitive types. Often, binary files contains large "raw" data arrays, usually, array of bytes. BinValueArray is container for such data types.
    Data arrays with size below a threshold (default size limit is 64k) are stored in memory, while larger arrays stay on disk and virtually mapped to memory.
  • BinStruct - represents a data structure like file header. Always stored in memory.
  • BinDocument - represents a top-level structure which keeps a link to the whole format schema and provides document-level functionality. Always stored in memory.
These classes inherit all BinNode properties and methods, and provide some additional data type-specific functionality.

There are two more special classes derived from BinNode returned by data query:
  • BinValueCalculated - represents a calculated value of primitive type which is not a part of the original document.
  • BinNodeCollection - represents a calculated collection of nodes created by query (filter expression) execution.
To obtain binary object content, you need to use InnerBin property.
To get text representation of binary object, use ToString() overridden method, for debugging purposes.

Below are properties and methods of these classes. BinNode methods and properties are not listed below for classes derived from BinNode, but, of course, they are inherited.

Class BinNode
public abstract class BinNode : ICloneable, IEnumerable, IBinNavigable

Represents the root class for the DOM hierarchy. Every object in a document is a BinNode.
Property Type Description
ParentNode BinNode, get/set The parent BinNode of this BinNode.
Position long, get/set Offset for the node from the beginning of the document. Set by BinReader.
NextSibling BinNode, get only The next sibling of this BinNode. Returns null if this is the last item.
PreviousSibling BinNode, get only The previous sibling of this BinNode. Returns null if this is the first item.
OwnerDocument BinDocument, get only The owner document of this BinNode. Returns null if the root node is not BinDocument.
RootNode BinNode, get only The root node. Returns BinDocument unless this node is in a document fragment.
SchemaInfo IBinSchemaInfo, get/set Node schema information object. Created by BinReader and BinValidator.
HelpString string, get only Returns help string if schema information is set and contains helpstring attribute.
HasAlternateView bool, get only Returns true if schema information is set and alternate view is set for stucture/item representing this node.
HasChildNodes bool, get only Returns true if this node has child nodes. If this node could potentially have child nodes (BinStruct), but actually has none, this property will return false.
ChildNodes BinNodeList, get only Returns a list of child nodes. If this node cannot have child nodes, returns null.
Size long, get only Returns size of this node in bytes.
Capacity long, get only Returns number of bytes this node could contain.
Count long, get only Returns number of items this node actually contains. BinValue.Count returns 1, BinValueArray.Count returns actual number of items in the array, BinStruct.Count return number of child nodes.
Description string, get only Returns description for the node.
InnerBin BinStorage, get/set Represents binary contents of the node. Is is possible to set contents of the node using this property. However, keep in mind that BinValueArrays with unlimited length will absorb the rest of the data despite the restriction rules. That is because set_InnerBin is a fast node filling operation, i.e., it will not execute expressions.
To fill complex structures correctly, you need to use parsing, i.e., ReadFrom method, or alternate views.
InnerBinStream Stream, get Allows to read binary representation of node as a stream. Returned stream should not be used to fill the node, in most cases it will be read-only.
Provided a a fast and simple altenative to InnerBin.GetStream() operation, to avoid to close disposable InnerBin result and stream returned from GetStream(). This operation is specially optimized and should be used if possible to read node contents as a Stream.
NodeType BinNodeType, get only Returns type of the node.
Dependencies BinNodeList, get only Returns a list of nodes which current node depends of. Dependencies will be detected if current node has expressions (rules) with other nodes involved. Dependencies will be detected if special dependencies detection mode property ([1], [2], [3]) is set during parsing or validation of document.
If dependencies detection is turned off or current node is not dependent from other nodes, returns null.
Method Parameters Description
SelectNodes string binpath, returns BinNodeCollection Runs BinPath query using this node as an expression context and return collection of nodes as a result.
SelectSingleNode string binpath, returns BinNode Runs BinPath query using this node as an expression context and return a single node result.
CreateNavigator returns BinPathNavigator Implementation of IBinNavigable.CreateNavigator. Returns a BinPathNavigator for this node.
ContentChanged returns void Invalidates cached alternate view. If you changed BinNode directly, call this function at the end of manipulations. "Directly" means using methods of ChildNodes node list of structure, or directly modify Variant returned by BinValue.Value.
This approach is not recommended. Please use operations provided by BinNode-derived classes instead. They are safe, i.e., you don't need to call ContentChanged after them.
GetAlternateView string name, BinEventHandler handler, returns BinNode Returns alternate view for this BinNode if it was declared in schema description. Otherwise, returns null.
Name should be used if this node has several views and you need to get some particular one. In other cases, set name parameter to empty string or null.
SetAlternateView BinNode node, string name, BinEventHandler handler, returns void Uses contents of this node as a source for alternate view if alternave view was declared in schema description. Otherwise, does nothing. On error, calls back handler delegate. Name should be used if this node has several views and you need to use some particular one. In other cases, set name parameter to empty string or null.
GetVirtualPosition BinNode node, returns long Returns relative position of provided node from this node. When you need to find location of some node in the file, call rootNode.GetVirtualPosition(someNode);
This method works properly even if the node is a result of query (BinNodeCollection).
WriteTo Stream stream, returns void Saves a binary node contents to a stream.
ReadFrom Stream stream, BinEventHandler handler, returns void Reads binary data to this node. BinValue and BinValueArray just fills themselves with data from stream, according to Capacity value. BinStruct and BinDocument do real data parsing with validations, rules executions and error handling.
Calls back handler on errors.
DumpDependencies returns string Returns a string representing a list of dependency nodes, each converted to string.

Class BinValue
public class BinValue : BinNode

This class represents a single value of primitive type.
Constructor Parameters Description
BinValue None Default constructor. Creates a value of type int64 equal to 0.
BinValue TypeCode type Creates a value of the specified type equal to 0.
BinValue Variant var Initializes with a copy of the provided Variant.
BinValue Variant var, bool copy Initializes with a copy of the provided Variant if "copy" parameter is true. Otherwise, initializes with a link to the Variant. Use this constructor to create BinValues which share their contents.
Property Type Description
Value Variant, get only Returns data value for this node.
BigEndian bool, get/set Get/set the endianness for the value.
VarType TypeCode, get only Get data type of the underlying value.
IsPointer boolean, get only Test is the value actually a pointer.
Method Parameters Description
GetPointerLocation returns long Calculate a location where pointer value ponts to. If ths value is not a pointer or if pointer is invalid (calculated by pointer's rules), this method returns -1.
ToString returns void Textual representation of object.

Class BinValueArray
public class BinValueArray : BinNode

This class represents an array of primitive type values.
BinValueArray can contain values of any supported types. Maximum number of items can be limited or unlimited. For limited size array, set_InnerBin or ReadFrom operations must read exactly the same amount of data as specified maximum size, or BinException will be thrown. For unlimited length array, you can fill array with any amount of data. For this type of array, maximum size shall be set to long.MaxValue.
Constructor Parameters Description
BinValueArray None Default constructor. Creates an unlimited length value array of bytes.
BinValueArray TypeCode type, long size Creates a value array of the specified type and maximum size.
BinValueArray TypeCode type, Stream stream, long position, long size Creates a value array of the specified type and maximum size. If possible, this constructor will create mapped BinValuearray, i.e., it will be already prepopulated with data from the Stream using specified starting position and size. There is no need to fill this array manually.
If you will modify a "mapped" array, it will convert itself into a tempfile-based array and save contents to a temp file. In general, you should not worry about these implementation details unless you are fine-tuning performance of your application.
Property Type Description
ElementSize long, get only Size of a single array item, according to array type.
Limit long, get/set Maximum amount of items array could contain.
ByteLimit long, get/set Maximum array size in bytes.
BigEndian bool, get/set Get/set the endianness for the values.
VarType TypeCode, get only Get data type of the underlying values.
Method Parameters Description
GetValue long index, returns Variant Returns array item by index. Index is item number. First item has index 0.
AddValues byte[] data, returns void Add data to BinValueArray from byte array.
AddValues BinStorage data, returns void Add data to BinValueArray from BinStorage.
AddValues Stream data, returns void Add data to BinValueArray from Stream.
FinishAddValues returns void Call this method to finish adding data. If this array has limited size, checks internal data length.
Clear returns void Clears the array.
ToString returns void Textual representation of object.

Class BinStruct
public class BinStruct : BinNode

This class represents a binary structure in a document. It is a container for other BinNodes and has a set of methods and properties manage these BinNodes.
Initially, BinStruct instance is "anonymous", i.e., does not have any specific data type. Structure has a type and could be parsed or validated only if SchemaInfo is assigned.
Please do not use BinNodeList methods to add/insert/delete nodes, because they will not correctly assign parent node for child nodes. Use BinStruct methods instead.
Constructor Parameters Description
BinStruct None Default constructor. Creates an empty structure of unknown type.
Property Type Description
Item (indexer) long, get only Returns BinNode child item by index.
FirstChild BinNode, get only Returns first child item.
LastChild BinNode, get only Returns last child item.
LongDescription string, get only Returns helpstring of the structure.
Method Parameters Description
AppendChild BinNode newChild, returns BinNode Appends an item to the list of nodes. Returns appended node.
InsertAfter BinNode newChild, BinNode refChild, returns BinNode Inserts an item to the list of nodes after refChild. Returns inserted node.
InsertBefore BinNode newChild, BinNode refChild, returns BinNode Inserts an item to the list of nodes before refChild. Returns inserted node.
PrependChild BinNode newChild, returns BinNode Inserts an item to the beginning of the list of nodes. Returns inserted node.
RemoveChild BinNode child, returns BinNode Removes an item from the list of nodes, if specified node was a child of the structure; otherwise does nothing. Returns removed node.
RemoveFirstChild returns void Removes the first item from the list of child nodes.
RemoveLastChild returns void Removes the last item from the list of child nodes.
RemoveAll returns void Removes all items from the list of child nodes.
ReplaceChild BinNode newChild, BinNode oldChild, returns BinNode Replaces oldChild with newChild, if oldChild was a child of the structure; otherwise does nothing. Returns newChild node.
ToString returns void Textual representation of object.

Class BinDocument
public class BinDocument : BinStruct

This class represents a binary document. It is derived from BinStruct, therefore, it provides all BinStruct functionality.
Also, BinDocument includes a set of static helper methods to create and initialize various BinNode classes, to simplify automated document creation from client software.
Constructor Parameters Description
BinDocument None Default constructor. Creates an empty document of unknown type.
Property Type Description
Schema BinSchema, get/set Schema for use to parse/validate this document.
DetectDependencies bool, get/set Turns on/off dependencies detection mechanism. Works in ReadFrom implementation and Validate method.
Method Parameters Description
static CreateStructure BinNode[] nodes, returns BinStruct Helper function which creates unnamed BinStruct and fills it with child nodes.
static CreateValue TypeCode type, object value, returns BinValue Helper function which creates BinValue of given type and assigns it a value.
static CreateValueArray TypeCode type, long size, byte[] data, returns BinValueArray Helper function which creates BinValueArray of the provided type and size and fills it with data.
static CreateValueArray TypeCode type, long size, Stream data, returns BinValueArray Helper function which creates BinValueArray of the provided type and size and fills it with data from Stream.
CreateStructure string name, returns BinStruct Helper function which creates BinStruct with appropriate SchemaInfo of a specified type.
Validate BinSchema schema, BinEventHandler handle, returns void Validates document against the schema. Initializes Schema property.
static Load Stream dump, returns BinDocument Deserializes and returns BinDocument from a stream.
Save Stream dump, returns void Serializes BinDocument to a stream.
FindNodeByPosition long pointer, returns BinNode Finds a node occupying given position in the document. This will be always data container node, BinValue or BinValueArray. If node for given position not found, returns null.

Class BinValueCalculated
public class BinValueCalculated : BinValue

BinValueCalculated should never appear in a document structure. It could only be returned as a result of query operation and represents a calculated value of some primitive type. It does not have a parent node.
BinValueCalculated is based on BinValue and does not provide any additional functionality.
NodeType property returns BinNodeType.CALCVALUE.

Class BinNodeCollection
public class BinNodeCollection : BinNode

BinNodeCollection should never appear in a document structure. It could only be returned as a result of query operation and represents a collection of nodes. It does not have a parent node and does not set itself as a parent node for child nodes.
BinNodeCollection is based on BinNode and does not provide any additional functionality. All operation with child nodes should be made through BinNodeList returned by Children property.
Use BinNodeCollection as an aggregated BinNode. It is possible to get/set InnerBin value of the collection, perform ReadFrom (parsing) and WriteTo operations.
GetVirtualPosition implementation allows to use it as a root node for some view, and will return correct virtual position even if collection consists of non-adjacent nodes.
NodeType property returns BinNodeType.COLLECTION.
Property Type Description
Item (indexer) long, get only Returns BinNode child item by index.
Method Parameters Description
AddUnique BinNode node, returns void Adds a node to collection if it is not in collection yet.

Class BinNodeList
public class BinNodeList : HugeList<BinNode>

This class represents a list of nodes and provides a full set of functionality for manipulations with this list.
BinNodeList is based on generic HugeList doubly-linked list.

Class BinException
public class BinException : SystemException

This class is a class of exception objects thrown when binary document parsed, validated or incorrectly manipulated.
Constructor Parameters Description
BinException BinNode obj Constructs an exception with source node.
BinException BinNode obj, string message Constructs an exception with source node and a message.
BinException BinNode obj, string message, long pos Constructs an exception with source node, a message and a position.
BinException BinNode obj, string message, Exception e Constructs an exception with source node, a message and inner exception.
Property Type Description
Position long, get only Returns position of the error in a document.
SourceNode BinNode, get only Returns node which caused the exception.

Class BinEventArgs
public class BinEventArgs : EventArgs

Contains information about error or warning occured during binary document processing.
Constructor Parameters Description
BinEventArgs BinException e, SeverityType s Initializes object with appropriate values.
Property Type Description
Exception BinException, get only Returns exception information.
Severity SeverityType, get only Returns information about severity of error.

Enumeration BinNodeType
public enum BinNodeType

Represents type of node.
Member Description
VALUE The node is value of a primitive type.
VALUEARRAY The node is array of values of a primitive type.
STRUCT The node is a structure.
DOCUMENT The node is a document.
CALCVALUE The node is a calculated value.
COLLECTION The node is a node collection.

Delegate BinEventHandler
public delegate void BinEventHandler(
Object sender,
BinEventArgs e
);

Represents the callback method that will handle binary document parsing/validation events.

See also: