Binary Schema Object Model classes

The Binary Schema Object Model (SOM) is API that allows you to create, edit, and validate schemas programmatically.
Binary Schema is a collection of objects that could be compiled, verified, saved, loaded and used together to parse and validate binary documents.
Every class in SOM have its own ToString() method overridden which should be used to re-create schema text from its internal representation. This allows to inspect all optimization performed during schema compilation.

Class BinSchemaObject
public class BinSchemaObject

Represents the root class for the SOM hierarchy.
Property Type Description
Parent BinSchemaStruct, get/set The parent structure of this BinSchemaObject.

Class BinSchemaAnnotation
public class BinSchemaAnnotation

Contains a dictionary of key-value pairs which represents additional information about schema elements.
Both key and value are strings.
Constructor Parameters Description
BinSchemaAnnotation None Default constructor.
Property Type Description
Items Dictionary<string, string>, get/set Dictionary of key-value string typed objects.
Method Parameters Description
ToString returns void Textual representation of object.

Class BinSchemaAnnotated
public class BinSchemaAnnotated : BinSchemaObject

The base class for any schema element that can contain annotation elements.
Property Type Description
Annotation BinSchemaAnnotation, get/set Annotation for this object.
HelpString string, get only Helper property, returns annotation value for "helpstring" key if it exists, otherwise returns an empty string.
Method Parameters Description
AnnotationValueExists string key, returns bool Returns true if annotation value with given key exists.
GetAnnotationValue string key, returns string Returns annotation value for a given key; if does not exist - return an empty string.
ToString returns void Textual representation of annotation if present.

Class BinSchemaDictionary
public class BinSchemaDictionary : BinSchemaObject

This class represents a Dictionary schema object used for lookup BinPath function.
Constructor Parameters Description
BinSchemaDictionary None Default constructor.
Property Type Description
Name string, get/set Name of dictionary object.
Count int, get only Elements count in dictionary object.
Method Parameters Description
Add string key, string value, returns void Adds a key-value pair into a dictionary object. Values will be pased and converted into appropriate types.
Values enclosed with double quotation marks will be converted into strings; values enclosed with single quotation marks - into characters. Other values will be converted into numbers of a proper type.
Add Variant key, Variant value, returns void Adds a key-value pair into a dictionary object. Values are already have proper types. This method will insert into the dictionary copies of these values.
Get Variant key, returns Variant Returns a value for this key or null if it does not exist.
ToString returns void Textual representation of object.

Class BinSchemaView
public class BinSchemaView : BinSchemaObject

This class represents a View schema object.
Constructor Parameters Description
BinSchemaView None Default constructor.
Property Type Description
Name string, get/set Name of view object.
ConversionRule string, get/set Conversion rule of view object.
Type BinSchemaType, get/set Type of alternate view.
ArrayDimensions string, get/set Dimension expression for type of alternate view.
EncodingHandler string, get/set Encoding handler of alternate view, in "namespace:function" or "namespace" form.
NameSpace string, get only Namespace value for encoding handler of alternate view.
Function string, get only Function (class) value for encoding handler of alternate view.
Method Parameters Description
ToString returns void Textual representation of object.

Class BinSchemaDirectoryElement
public class BinSchemaDirectoryElement : BinSchemaObject

This class represents a Directory schema object.
Constructor Parameters Description
BinSchemaDirectoryElement None Default constructor.
Property Type Description
Name string, get/set Name of view object.
PointerRule string, get/set Rule to calculate pointer value.
AcceptRule string, get/set Rule to validate pointer before use.
Type BinSchemaType, get/set Type of alternate view.
ArrayDimensions string, get/set Dimension expression for type of alternate view.
Method Parameters Description
ToString returns void Textual representation of object.

Class BinSchemaNamespace
public class BinSchemaNamespace : BinSchemaAnnotated

This class represents a namespace in a schema.
Constructor Parameters Description
BinSchemaNamespace None Default constructor.
Property Type Description
Name string, get/set Name of namespace.
Location string, get/set Location of namespace target object (assembly).
Type NameSpaceType, get/set Type of namespace: DLL, COM or DotNet.
Method Parameters Description
ToString returns void Textual representation of object.

Class BinSchemaType
public class BinSchemaType : BinSchemaObject

This class represents type of an item in a schema.
Constructor Parameters Description
BinSchemaType None Default constructor. Type gets initialized as uint32.
BinSchemaType BinSchemaStruct struct Type gets initialized as a document/structure reference.
BinSchemaType BinTypeCode code Type initialized as a specified primitive type.
Property Type Description
Name string, get/set Name of type.
TypeCode BinTypeCode, get/set Type code.
Structure BinSchemaStruct, get/set Structure reference for structure type.
BigEndian bool, get/set This value inidicates whether the value is big endian. It does nothing for values of irrelevant types like structure, byte, or float point numbers.
TypeName string, get only Name of type in string form.
Method Parameters Description
ToString returns void Textual representation of object.
Also, BinSchemaType provides a full set of equality API: operator ==, operator !=, GetHashCode(), IComparable.Equals.

Class BinSchemaItem
public class BinSchemaItem : BinSchemaAnnotated

This class represents a structure/document item in a schema.
Constructor Parameters Description
BinSchemaItem None Default constructor.
Property Type Description
Name string, get/set Name of item.
Types List<BinSchemaType>, get only List of type of current item. Item may contain several types (enumeration).
ArrayDimensions string, get/set Dimension expression if item is array.
Restrictions string, get/set Restrictions rule for the item. Will be ignored for enumerations and arrays of enums.
Implicit bool, get/set Is flag "implicit" specified for this item.
Optional bool, get/set Is flag "optional" specified for this item.
AllowEmpty bool, get/set Is flag "allowempty" specified for this item.
Method Parameters Description
ToString returns void Textual representation of object.

Class BinSchemaStruct
public class BinSchemaStruct : BinSchemaAnnotated

This class represents a structure in a schema.
Constructor Parameters Description
BinSchemaStruct None Default constructor.
Property Type Description
Name string, get/set Name of structure.
Items List<BinSchemaItem>, get only List of items.
AcceptRule string, get/set AcceptRule expression.
IsDocument bool, get only Indicates that the structure is actually a BinSchemaDocument.
IsPrivate bool, get/set Indicates that this structure was included into the schema from external include file. This property is intended for using by schema parsers.
IsOptimized bool, get only Indicates that this structure was optimized by schema parser.
Method Parameters Description
ToString returns void Textual representation of object.

Class BinSchemaDocument
public class BinSchemaDocument : BinSchemaStruct

This class represents a document in a schema.
Document is based on structure.
Constructor Parameters Description
BinSchemaDocument None Default constructor.
Property Type Description
MimeTypes IEnumerable<string>, get only Returns set of mime types assigned to the current document with "mime_type" annotation.
Extensions IEnumerable<string>, get only Returns set of extensions assigned to the current document with "extension" annotation.

Class BinSchema
public class BinSchema

This class represents a binary document schema which contains all items provided in the schema description.
BinSchema validates and compile schema.
Schema must be compiled and must be valid before use for documents parsing and validation.
Constructor Parameters Description
BinSchema None Default constructor.
BinSchema BinSchema Copy constructor.
Property Type Description
Namespaces List<BinSchemaNamespace>, get only Provides access to collection of namespaces.
Structures List<BinSchemaStruct>, get only Provides access to collection of structures, including documents.
Dictionaries List<BinSchemaDictionary>, get only Provides access to collection of dictionaries.
Views List<BinSchemaView>, get only Provides access to collection of views.
Directory List<BinSchemaDirectoryElement>, get only Provides access to collection of directory elements (objects).
Documents IEnumerable<BinSchemaDocument>, get only Provides access to temporary collection of documents, excluding ones marked as private.
IsCompiled bool, get only Indicates that the schema is compiled and verified.
IsValid bool, get only Indicates that the schema is valid.
Credits string, get/set Represents a credits value from header information block.
Comments string, get/set Represents a comments value from header information block.
License string, get/set Represents a license value from header information block.
Version int, get/set Represents a version value from header information block.
Method Parameters Description
FindStructure string name, returns BinSchemaStruct Finds a structure by name in internal structures array. If not found, returns null.
FindView string name, returns BinSchemaView Finds a view by name in internal views array. If not found, returns null.
FindDirectory string name, returns BinSchemaDirectoryElement Finds a directory element by name in internal directory array. If not found, returns null.
FindNamespace string name, returns BinSchemaNamespace Finds a namespace by name in internal namespaces array. If not found, returns null.
Compile BinValidationEventHandler handler, returns void Compiles a schema, checks all expressions and makes optimizations. On error, if handler == null, throws BinSchemaException.
CheckExpression BinNode context, BinPathExpression expr, BinValidationEventHandler han, returns void Checks an expression in context of node. On error, if handler == null, throws BinSchemaException.
Node must contain a valid SchemaInfo structure to use this method.
static Read IBinSchemaReader reader, TextReader trd, BinValidationEventHandler han, returns BinSchema Parses a schema loaded from TextReader using IBinSchemaReader interface, compiles a schema and returns it. On error, calls BinValidationEventHandler.
static Load Stream dump, returns BinSchema Deserializes a schema and returns it.
Save Stream dump, returns void Serializes the schema.
ToString returns void Textual representation of object.

Class BinSchemaException
public class BinSchemaException : SystemException

This class contains exception details for exceptions thrown when BinSchema compiler and validator encounter an error.
Constructor Parameters Description
BinSchemaException BinSchemaObject obj Constructs an exception with source object.
BinSchemaException BinSchemaObject obj, string message Constructs an exception with a source object and a message.
BinSchemaException BinSchemaObject obj, string message, int line Constructs an exception with a source object, a message, and a line number.
BinSchemaException BinSchemaObject obj, string message, Exception e Constructs an exception with a source object, a message, and an inner exception.
Property Type Description
LineNumber int, get only Returns a line number of the error (in the bdd file). If the error cannot be linked to a specific line, returns -1.
SourceSchemaObject BinSchemaObject, get only Returns an object which caused the error.

Class BinSchemaInfo
public class BinSchemaInfo : IBinSchemaInfo

Provides schema information for validated binary node.
Constructor Parameters Description
BinSchemaInfo None Default constructor. Creates empty schema info object.
BinSchemaInfo BinSchemaItem bsItem, BinSchemaType bsType, bool isValid Initializes schema info object with provided values.

Class BinValidationEventArgs
public class BinValidationEventArgs : EventArgs

Encapsulates information about validation error/warning.
Constructor Parameters Description
BinValidationEventArgs BinSchemaException ex, SeverityType severity Initializes object with provided values.
Property Type Description
Exception BinSchemaException, get only Returns an exception information.
Severity SeverityType, get only Returns an severity of the error.

Interface IBinSchemaInfo
public interface IBinSchemaInfo

Provides an interface for current node schema information access.
Property Type Description
SchemaItem BinSchemaItem, get only Returns a schema item corresponding to the current node.
SchemaType BinSchemaType, get only Returns a schema type corresponding to the current node.
IsArray bool, get only Returns true if a schema item contains a valid ArrayDimensions value.
Validity bool, get only Returns true if schema information is valid (current node is validated successfully).

Interface IBinSchemaReader
public interface IBinSchemaReader

Defines an iterface for schema parsers.
Any class that implements this interface and parses schema description in some format (C-like, XML, etc) and translates it into BinSchema object, could be used as an alternative schema parser.
Method Parameters Description
Parse TextReader trd, BinSchema bschema, BinValidationEventHandler handler, returns void Reads schema description from TextReader, fills BinSchema and reports errors to handler if it is not null.

Enumeration BinTypeCode
public enum BinTypeCode

Provides information about type of BinNode.
Member Description
ITEM_U8 unsigned byte
ITEM_S8 signed byte
ITEM_U16 unsigned short
ITEM_S16 signed short
ITEM_U32 unsigned int
ITEM_S32 signed int
ITEM_U64 unsigned long
ITEM_S64 signed long
ITEM_CHAR ACSII char
ITEM_WCHAR Unicode char
ITEM_FLOAT single
ITEM_DOUBLE double
ITEM_STRUCT Structure. This type needs to be supplemented by a name of specific structure.

Enumeration NameSpaceType
public enum NameSpaceType

Provides information about type of namespace. In current version, it must be always NAMESPACE_DOTNET.
Member Description
NAMESPACE_DOTNET The namespace object is a dotnet assembly.
NAMESPACE_COM The namespace object is a COM server.
NAMESPACE_DLL The namespace object is a DLL.

Delegate BinValidationEventHandler
public delegate void BinValidationEventHandler(
Object sender,
BinValidationEventArgs e
);

Represents the callback method that will catch binary schema validation events.

See also: