Structure definitions

A structure is a named set of fields. It can inherit fields from other structures or belong to a group of structures, and it has a condition that is based on fields and variables and that is evaluated to decide whether the structure is detected. Finally, each structure has a set of actions that are run after the structure is detected.

A structure definition has the following mandatory and optional XML attributes and elements:

name

A mandatory XML attribute that specifies a unique ID for the structure. In the following example, the name of the structure is header: 


<structure name="header">
</structure>

base

The optional parent structure from which all fields are inherited.

field

A structure must have at least one field, either by inheriting fields using the base XML element, by defining fields using the field XML element, or by combining the base and field elements. Each field must have a unique name and a valid type: boolean, int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32, float64, rstring[n], or blob[n]. For rstring and blob types, size information must be specified. For integer and floating point types, you can specify the little or big endian type. If you do not, the default value for these types is little endian. For more details about endianness, see Endianness.

The order of the field definitions is important because this operator assumes that the fields occur in the input data stream in the same order in which they are defined. The byte offset of each defined field within the structure (the Nth field) is calculated by adding the type-dependent sizes of the fields (1 through N-1). For example, the RECORD_TYPE field starts at offset 0 (no field in front), the IMSI field at offset 1 (uint8 has a size of one byte), the VERSION field at offset 11 (rstring size is specified as "10"), and the DUMMY field at offset 15 (uint32 size is 32 bit, or 4 bytes): 


<field name="RECORD_TYPE" type="uint8"/>
<field name="IMSI" type="rstring" size="10"/>
<field name="VERSION" type="uint32" endianness="big"/>
<field name="DUMMY" type="blob" size="120"/>

If an instance of this operator supports multiple versions of structures, a newer version of a structure often extends an older version by inheriting the fields of the older version and adding new fields.

This operator supports the declaration of a base structure from which the current structure inherits all fields. Neither the actions nor the condition of the older version are inherited.

In the following example, the only field of the event_v1 structure is RECORD_TYPE. The event_v2 structure inherits RECORD_TYPE (from event_v1) and adds the new IMSI_ADDR field. Inherited fields are located in front of new fields, for example: 


<structure name="event_v1">
	<condition>
			...
	</condition>
	<field name="RECORD_TYPE" type="uint8"/>
</structure>
<structure name="event_2">
	<condition>
			...
	</condition>
	<base name="event_v1"/>
	<field name="IMSI_ADDR" type="rstring" size="10"/>
</structure>

condition

The Boolean expression that is evaluated to determine whether a corresponding structure is detected. Before a condition is evaluated, however, the internal payload buffer must receive at least as many bytes as the size of the corresponding structure. For example, if the structure is 10 bytes, this operator must have at least 10 unprocessed bytes before the condition is evaluated.

If the structure definition file contains only the definition of a single structure, this condition is optional. But if the file contains more than one structure or if structure-based synchronization is specified, the condition is mandatory.

Each condition must be unique. If two or more conditions are fulfilled, only one structure is chosen at random to be processed. The system does not generate messages to indicate uniqueness violations during the compilation or runtime.

A condition consists of one or more terms. The following terms are supported:

<logicOp op="and|or">

The logic operation supports AND (C++: "&&") and OR (C++: "||") logic. The term can have any number of other terms, including logicOp itself, for example, an AND operation that contains an OR and another AND operation.

<cmp op="equal|notEqual|lessThan|greaterThan|lessOrEqual|greaterOrEqual">

This operation compares a variable or field value (the left-hand side argument, or LHS) with a variable, field, or constant value (the right-hand side argument, or RHS) and applies the given compare operator. For example, <logicOp op="lessThan"> means LHS < RHS.

<not>

The NOT operation inverts the result of its inner term.

<in>

The IN operation behaves identically to a <logicOp op="or"> operation with many <cmp op="equal"> operations, except that is has better performance.

Examples

The following example shows a condition that is met if the RECORD_TYPE equals 1 and the RECORD_LENGTH equals 93: 


<condition>
	<logicOp op="and">
		<cmp op="equal">
			<field name="RECORD_TYPE"/>
			<value>1</value>
		</cmp>
		<cmp op="equal">
			<field name="RECORD_LENGTH"/>
			<value>93</value>
		</cmp>
	</logicOp>
</condition>

The following example shows a condition that is met if the RECORD_TYPE equals 16, the RECORD_LENGTH equals 24, and the version variable has a value in range 0 till 4: 


<condition>
	<logicOp op="and">
		<cmp op="equal">
			<field name="RECORD_TYPE"/>
			<value>16</value>
		</cmp>
		<cmp op="equal">
			<field name="RECORD_LENGTH"/>
			<value>24</value>
		</cmp>
		<in>
			<variable name="version"/>
			<value>0</value>
			<value>1</value>
			<value>2</value>
			<value>3</value>
			<value>4</value>
		</in>
	</logicOp>
</condition>

The following example shows a condition that is met if the version variable is less than 5 but neither 0, nor 1: 


<condition>
	<not>
		<logicOp op="or">
			<cmp op="greaterOrEqual">
				<variable name="version"/>
				<value>5</value>
			</cmp>
			<in>
				<variable name="version"/>
				<value>0</value>
				<value>1</value>
			</in>
		</logicOp>
	</not>
</condition>

group

Specifies the group to which the structure belongs. Each group has a group condition. This element is optional.

action

Specifies one or more actions to be run if this structure is detected. This element is optional.