BroValue Class

BroValue Class

Represents a Bro value. Implicitly castable to all BroType wrapper classes, structures and applicable .NET data types.

Inheritance Hierarchy

SystemObject
BroccoliSharpBroValue
BroccoliSharpBroField

Namespace: BroccoliSharp
Assembly: BroccoliSharp (in BroccoliSharp.dll) Version: 1.0.5434.15853

Syntax

JavaScript

Copy

public class BroValue : IEquatable<BroValue>

Public Class BroValue
	Implements IEquatable(Of BroValue)

type BroValue =  
    class
        interface IEquatable<BroValue>
    end

public class BroValue implements IEquatable<BroValue>

BroccoliSharp.BroValue = function();

Type.createClass(
	'BroccoliSharp.BroValue',
	null,
	IEquatable`1);

The BroValue type exposes the following members.

Constructors

	Name	Description
	BroValue	Creates a new BroValue.

Top

Methods

	Name	Description
	Equals(Object)	Determines whether the specified Object is equal to the current BroValue. (Overrides ObjectEquals(Object).)
	Equals(BroValue)	Indicates whether the current BroValue is equal to another BroValue of the same BroType.
	Finalize	Allows an object to try to free resources and perform other cleanup operations before it is reclaimed by garbage collection. (Inherited from Object.)
	GetHashCode	Gets a hash code for this BroValue. (Overrides ObjectGetHashCode.)
	GetType	Gets the Type of the current instance. (Inherited from Object.)
	MemberwiseClone	Creates a shallow copy of the current Object. (Inherited from Object.)
	ToString	Returns a string that represents this BroValue. (Overrides ObjectToString.)

Top

Operators

	Name	Description
	Equality	Equality operator for BroValue.
	(Boolean to BroValue)	Implicitly converts Boolean value to a BroValue.
	(DateTime to BroValue)	Implicitly converts DateTime value to a BroValue.
	(IPAddress to BroValue)	Implicitly converts IPAddress value to a BroValue.
	(String to BroValue)	Implicitly converts String value to a BroValue.
	(BroAddress to BroValue)	Implicitly converts BroAddress value to a BroValue.
	(BroPacket to BroValue)	Implicitly converts BroPacket value to a BroValue.
	(BroPort to BroValue)	Implicitly converts BroPort value to a BroValue.
	(BroRecord to BroValue)	Implicitly converts BroRecord value to a BroValue.
	(BroSet to BroValue)	Implicitly converts BroSet value to a BroValue.
	(BroString to BroValue)	Implicitly converts BroString value to a BroValue.
	(BroSubnet to BroValue)	Implicitly converts BroSubnet value to a BroValue.
	(BroTable to BroValue)	Implicitly converts BroTable value to a BroValue.
	(BroTime to BroValue)	Implicitly converts BroTime value to a BroValue.
	(BroValue to BroString)	Implicitly converts BroValue to a BroString.
	(BroValue to String)	Implicitly converts BroValue to a String.
	(BroValue to BroPort)	Implicitly converts BroValue to a BroPort.
	(BroValue to BroAddress)	Implicitly converts BroValue to a BroAddress.
	(BroValue to IPAddress)	Implicitly converts BroValue to an IPAddress.
	(BroValue to BroSubnet)	Implicitly converts BroValue to a BroSubnet.
	(BroValue to BroVector)	Implicitly converts BroValue to a BroVector.
	(BroValue to BroRecord)	Implicitly converts BroValue to a BroRecord.
	(BroValue to BroTable)	Implicitly converts BroValue to a BroTable.
	(BroValue to BroSet)	Implicitly converts BroValue to a BroSet.
	(BroValue to BroPacket)	Implicitly converts BroValue to a BroPacket.
	(BroValue to BroTime)	Implicitly converts BroValue to a BroTime.
	(BroValue to DateTime)	Implicitly converts BroValue to a DateTime.
	(BroValue to Boolean)	Implicitly converts BroValue to a Boolean.
	(BroValue to Int32)	Implicitly converts BroValue to a Int32.
	(BroValue to UInt64)	Implicitly converts BroValue to a UInt64.
	(BroValue to Double)	Implicitly converts BroValue to a Double.
	(BroVector to BroValue)	Implicitly converts BroVector value to a BroValue.
	Inequality	Inequality operator for BroValue.

Top

Extension Methods

	Name	Description
	ConvertToType	Attempts to get a new BroValue based on the provided value converted to the specified type. (Defined by BroValueExtensions.)

Top

Properties

	Name	Description
	HasValue	Gets a flag that determines if this BroValue as an assigned value.
	Type	Gets type of BroValue.
	TypeName	Gets or sets optional name of specialized type of BroValue.
	Value	Gets value of BroValue.

Top

Remarks

Handling Bro Values

The Broccoli API defines a number of data types (see the BroType enumeration for the full list). From a BroccoliSharp perspective these data types are placed into two major classifications: value-types (e.g., Int32, UInt64, Double, BroTime, etc.), and reference-types (e.g., BroString, BroRecord, BroSet, etc.). A BroValue can represent either a value-type or a reference-type for any BroType implementation.

A BroValue acts as a versatile variant value class that can wrap all managed and native BroType implementations. The BroValue is an intermediate class that holds a reference to the actual type value and is implicitly castable to all BroType wrapper classes, structures and applicable .NET data types. The BroValue class exists to map strongly-typed BroType wrapper implementations and .NET native types to the void* values that are passed into the Broccoli C API.

Any Broccoli C API detail concerning use of opaque vs. transparent structures or getting a fixed pointer to a managed memory location for value and reference types are handled internally by BroccoliSharp via the BroValue class.

A BroValue is implicitly castable to all the BroType implementations. For reference-types, the BroValue just acts as a pointer to the value - casting to and from the type implementation and a BroValue only creates a reference to the type - not a new instance of the type. Casting a BroValue to a type other than the BroType implementation it represents will usually result in a null value. However, where applicable for the type, casting to and from related native .NET types is allowed. To change the type of a BroValue to another type, use the ConvertToType(BroValue, BroType) method. For value-types, casting to and from the type implementation and a BroValue always makes a copy of the value.

Note
BroPort, BroAddress and BroSubnet are immutable value-types, as a result, casting from these structures to a BroValue always makes a copy of the value. Also, although in the Broccoli C API the bro_string data type is a structure, the corresponding BroccoliSharp wrapper class, BroString, is a reference-type - however, this class is also immutable.

Design Notes

With a quick review of the BroValue source code one might be tempted to change the BroValueclass into a struct - it certainly meets all of the criteria for one. However, in the current design a BroField (used in conjunction with a BroRecord) directly inherits from BroValue and adds a field name property to allow column-name based lookups in a BroRecord. Through inheritance the BroField is effectively a BroValue for most all use cases and this greatly simplifies library usage when dealing with record sets. Unless you redesign how the record-set functionality currently uses the BroField as an extended BroValue, simply switching to a struct implementation means you can no longer inherit base functionality - in .NET, a struct cannot inherit a base class or other struct, it can only implement interfaces. To convert the BroValue to a struct using the current design would require using an interface for common functionality in the BroValue and BroField. The first thing you would lose in making these classes structs and implementing a common interface would be the ability to implicitly cast to and from common .NET types, e.g., a String. Custom Bro wrapper types could implement the needed interface easily enough, but you can't redefine native .NET types and have them implement your custom interface. Also, implicit conversion operations only work with concrete types, so you cannot implicitly convert an object to an interface - i.e., you can't make a native .NET string implicitly convertible to your custom interface.

Even with these constraints, this would not be the end of the world - you could go down the struct path without breaking the basic functionality of the library. However, making these changes would significantly reduce developer usage convenience of the library by having to always create Bro wrapper types to interact with the library. With the way the library is currently designed (with classes), a String can be a BroString, an IPAddress can be a BroAddress and a DateTime can be a BroTime, etc. without the developer having to deal with or think about the conversion details from native types to Bro wrapper types.

Another issue with the struct approach would be the performance penalties that would be incurred in the boxing and unboxing of the struct (value-type) as it was cast to and from its base interface (reference-type) before it could interact with any of Bro classes that work with values - and that being most all of them. As a side note, you might be thinking I actually tried using these classes as structs and later decided it was a bad idea - and if so, you would be right.

Reference

BroccoliSharp Namespace