Binary Top-Level classes

BinaryDOM API provides a set of classes. These classes will help you to load, parse and validate binary documents and schemas.
Library-level settings and licensing classes are described in this document too.

Class BinSchemaParser


public class BinSchemaParser : IBinSchemaReader

This is a schema parser for schemas written in Binary Data Description Language (BDDL).
It is possible to provide alternate data description language (for example, based on XML) and implement an alternative schema parser class. Alternate parser must implement IBinSchemaReader interface.
Constructor Parameters Description
BinSchemaParser None Default constructor.
Method Parameters Description
AddIncludeFolder string path, returns void Add a path to the list of include folders. When the parser processes include instruction, it uses the following order:
  1. If include instruction contains absolute path, parser uses this path as is.
  2. Parser tries to find a file in standard include folder (%Common_Appdata%/Miraplacid/BinaryDOM/Includes).
  3. Parser tries to find a file in each folder in the list of additional include folders, provided by AddIncludeFolder calls.
Parse TextReader textreader, BinSchema schema, BinValidationEventHandler handler, returns void Implementation of IBinSchemaReader interface. Parses a file from TextReader, fills BinSchema with parsed schema objects and calls back handler on errors.

Class BinReader


public class BinReader

This class parses raw binary data and converts it into BinDOM data structures according to metainformation (binary document schema).
Constructor Parameters Description
BinReader None Default constructor.
Property Type Description
DetectDependencies bool, get/set Turns on/off dependencies detection mechanism.
Method Parameters Description
Parse BinDocument doc, Stream stream, BinEventHandler handler, returns bool Parses a binary data from Stream, fills BinDocument binary objects and uses calls back handler on errors.
BinDocument must be empty and must have a valid reference to a document schema (Schema property must be set).
Returns true on success.
ParseStructure BinStruct node, Stream stream, BinEventHandler handler, returns bool Parses binary data from Stream, fills BinStruct binary objects and calls back handler on errors.
BinStruct must be empty and must have a valid reference to SchemaInfo with valid metainformation (SchemaType).
Returns true on success.

Class BinValidator


public class BinValidator

This class validates "manually built" BinDOM data structures against metainformation (binary document schema).
Constructor Parameters Description
BinValidator BinSchema schema Initializes an object with schema reference.
Property Type Description
DetectDependencies bool, get/set Turns on/off dependencies detection mechanism.
Method Parameters Description
Validate BinDocument doc, BinEventHandler handler, returns true Validates document against schema and calls back handler on errors. Returns true on success.
ValidateStructure BinStruct node, BinEventHandler handler, returns bool Validates binary structure and calls back handler on errors.
BinStruct must have a valid reference to SchemaInfo with valid metainformation (SchemaType).
Returns true on success.
ValidateStructure BinStruct node, string name, BinEventHandler handler, returns bool Validates a binary structure as a structure referred by "name" in schema and calls back handler on errors.
Returns true on success.

Class BinStreamDocument


public class BinStreamDocument : BinDocument
This class is works as a wrapper around BinDocument which keeps document and stream it uses in one entity.
When document is loaded from regular file (CanSeek), it will not read all the document data into memory, data arrays containing more than FileManager.PreswapSize bytes will be mapped on their actual locations in original document.
This greatly improves parsing speed and memory consumption, but, we need to keep the file open all the time we work with document.
This class allows to keep document and its file (Stream) together and close them at the same moment.
Constructor Parameters Description
BinStreamDocument Stream file Constructor accepting the file.
Method Parameters Description
Detach returns void Detach document from Stream without close the stream.
Useful if document is loaded with error and we need to attempt load another document from this source.
Close returns void Close the Stream explicitly.
Read BinEventHandler handler, returns void Calls BinDocument implementation of ReadFrom method with document Stream

Class BinSchemaSet


public class BinSchemaSet : List<BinSchema>

This class is designed to load and validate standard schema set. If you do not know up-front which data type you are going to use, or if you need to work with multiple data types, use this class in your application. This class loads documents and validate them against the loaded schemas.
This class is derived from a list of BinSchema, i.e. loaded schemas could be accessed as list elements.
Constructor Parameters Description
BinSchemaSet None Default constructor.
Property Type Description
SchemaErrors List<BinSchemaValidationEntry>, get only Get list of schemas validation errors, grouped by schema files. Each entry represents an errors set for a single file.
DocumentErrors List<BinDocumentValidationEntry>, get only Get list of documents loading errors, grouped by document filed. Each entry represents an errors set for a single file.
Method Parameters Description
LoadSchemas returns int Loads all schemas into BinSchemaSet internal collection from %Common_Appdata%/Miraplacid/BinaryDOM/BinSchemas folder.
If some schema is invalid, it will not be included into the collection. Returns number of schemas loaded.
LoadSchema string filename, returns bool Loads specific schema.
If specified schema is invalid, it will not be included into the collection. Returns true if schema was loaded successfully.
LoadDocument string filename, bool use_ext, bool detect_dependencies, returns BinStreamDocument Tries to load a document from a file specified by filename.
If use_ext parameter is true, method will try to load the document with schemas with file extension in their extensions list. If this parameter is false, method will try to load the document with each schema loaded into BinSchemaSet.
If document load failed, LoadDocument keeps trying to load it with the next applicable schema.
detect_dependencies parameter controls dependency detection process.
LoadDocumentAs string filename, string mime, bool detect_dependencies, returns BinStreamDocument Tries to load the document from a file specified by filename.
In this method, mime must not be null or empty. File extension will not be taken into consideration.
If provided mime type corresponds to mime_type provided in document schema, this method tries to load the document with the schema information.
If document load failed, LoadDocumentAs will not try to load it with any other schema.
detect_dependencies parameter controls dependency detection process.
ClearErrors returns void Clear all errors and returns BinSchemaSet object to initial state.

Class BinSchemaValidationEntry


public class BinSchemaValidationEntry : List<BinValidationEventArgs>

Represents collection of errors related to a specific schema file.
This class is derived from a list of BinValidationEventArgs, i.e. BinValidationEventArgs could be accessed as list elements.
Constructor Parameters Description
BinSchemaValidationEntry string filename Initializes BinSchemaValidationEntry object for the specified file.
Property Type Description
File string, get only Returns file name.

Class BinDocumentValidationEntry


public class BinDocumentValidationEntry : List<BinEventArgs>

Represents collection of errors related to a specific document.
This class is derived from a list of BinEventArgs, i.e. BinEventArgs could be accessed as list elements.
Constructor Parameters Description
BinDocumentValidationEntry BinSchemaDocument bdoc Initializes BinDocumentValidationEntry object for the specified schema document.
Property Type Description
Document BinSchemaDocument, get only Returns schema document.

Class BinDocumentEnumerator


public class BinDocumentEnumerator : IEnumerable<BinNode>

Represents collection of all nodes in document to help use document in Lynq queries.
Constructor Parameters Description
BinDocumentEnumerator BinDocument doc Initializes collection of nodes. Nodes will be enumerated in order of document tree traversal.

See also: