Functions for writing dissectors

Prefs

The table of preferences of a Protocol. (Reference)

function	description
prefs:__newindex(name, pref)	Creates a new preference
prefs:__index(name)	Gets the value of a preference setting

prefs:__newindex(name, pref)

Description
- Creates a new preference
Parameters
- name : string
  - The name of this preference
  pref : Pref
  - A valid but still unassigned Pref object
Errors
- Unknown Pref type or preference already exists
Example
- ```
   1 -- create a Boolean preference named "bar" for Foo Protocol
   2 -- (assuming Foo doesn't already have a preference named "bar")
   3 proto_foo.prefs.bar = Pref.bool( "Bar", true, "Rum and coke" )
```

prefs:__index(name)

Description
- Gets the value of a preference setting
Parameters
- name : string
  - The abbreviation of this preference
Returns
- string, number : The current value of the preference
Errors
- Preference does not exist for the protocol
Example
- ```
   1 -- print the value of Foo's preference named "bar"
   2 debug( "bar = " .. proto_foo.prefs.bar )
```

Pref

A preference of a Protocol. (Reference)

function	description
Pref.bool(label, default, descr)	Creates a Boolean preference (i.e., a checkbox) to be added to a Protocol's prefs table
Pref.uint(label, default, descr)	Creates an [unsigned] integer preference (i.e., a numeric textbox) to be added to a Protocol's prefs table
Pref.string(label, default, descr)	Creates a string preference (i.e., a textbox) to be added to a Protocol's prefs table
Pref.enum(label, default, descr, enum, radio)	Creates an enum preference (i.e., radio button or Combobox) to be added to a Protocol's prefs table
Pref.range(label, default, descr, max)	Creates a range preference (i.e., numeric textbox) to be added to a Protocol's prefs table
Pref.range(label, default, descr, range, max)	Creates a range preference (i.e., numeric textbox) to be added to a Protocol's prefs table (DEPRECATED)
Pref.statictext(label, descr)	Creates a static text field (i.e., label) to be added to a Protocol's prefs table

Pref.bool(label, default, descr)

Description
- Creates a Boolean preference (i.e., a checkbox) to be added to a Protocol's prefs table
Parameters
- label : string
  - The label text for this preference
  default : boolean
  - The default value of this preference
  descr : string
  - A description of this preference (shown as tooltip)
Returns
- Pref : The newly created preference. The value returned from the preference is a Boolean.

Pref.uint(label, default, descr)

Description
- Creates an [unsigned] integer preference (i.e., a numeric textbox) to be added to a Protocol's prefs table
Parameters
- label : string
  - The label text for this preference
  default : number
  - The default value of this preference
  descr : string
  - A description of this preference (shown as tooltip)
Returns
- Pref : The newly created preference. The value returned from the preference is an [unsigned] integer.

Pref.string(label, default, descr)

Description
- Creates a string preference (i.e., a textbox) to be added to a Protocol's prefs table
Parameters
- label : string
  - The label text for this preference
  default : string
  - The default value of this preference
  descr : string
  - A description of this preference (shown as tooltip)
Returns
- Pref : The newly created preference. The value returned from the preference is a string.

Pref.enum(label, default, descr, enum, radio)

Description

Creates an enum preference (i.e., radio button or Combobox) to be added to a Protocol's prefs table

Parameters

label : string
- The label text for this preference
default : number
- The default value (of selection from enum table) of this preference
descr : string
- A description of this preference (shown as tooltip)
enum : EnumTable
- An EnumTable, which consists of an array of { index, label, value } , where:
  - index is a consecutive integer starting from 1
  - label is a string to display for the enum item
  - value is the integer value returned when the enum item is selected
radio : boolean
- Radio button (if true) or Combobox (if false)

Returns

Pref : The newly created preference. The value returned from the preference is the value of the selection from the enum table.

Example

   1 local OUTPUT_OFF        = 0
   2 local OUTPUT_DEBUG      = 1
   3 local OUTPUT_INFO       = 2
   4 local OUTPUT_WARN       = 3
   5 local OUTPUT_ERROR      = 4
   6 
   7 local output_tab = {
   8         { 1, "Off"              , OUTPUT_OFF },
   9         { 2, "Debug"            , OUTPUT_DEBUG },
  10         { 3, "Information"      , OUTPUT_INFO },
  11         { 4, "Warning"          , OUTPUT_WARN },
  12         { 5, "Error"            , OUTPUT_ERROR },
  13 }
  14 
  15 -- Create enum preference that shows as Combo Box under
  16 -- Foo Protocol's preferences
  17 proto_foo.prefs.outputlevel = Pref.enum(
  18         "Output Level",                 -- label
  19         OUTPUT_INFO,                    -- default value
  20         "Verbosity of log output",      -- description
  21         output_tab,                     -- enum table
  22         false                           -- show as combo box
  23 )
  24 
  25 -- Then, we can query the value of the selected preference.
  26 -- This line prints "Output Level: 3" assuming the selected
  27 -- output level is _INFO.
  28 debug( "Output Level: " .. proto_foo.prefs.outputlevel )

Pref.range(label, default, descr, max)

Pref.range(label, default, descr, range, max) (DEPRECATED)

Description

Creates a range preference (i.e., numeric textbox) to be added to a Protocol's prefs table

Parameters

label : string

The label text for this preference

default : string

The default range string (see Bug 5895 and Bug 5896)

A range string uses a special syntax to specify one or more ranges (of 16-bit unsigned integers). To specify all unsigned integers between m and n, the range string is: m-n . If m is omitted, the minimum end of the range is set to 1. If n is omitted, the maximum end of the range is set to 65535. If only a single integer is specified (no hyphen), the minimum and maximum are set to that integer. Multiple range entries are separated by commas.

Example range strings

range string	meaning
`-45`	integers 1 through 45, inclusive
`4567-`	integers 4567 through 65535, inclusive
`5`	only integer 5
`123-200`	integers 123 through 200, inclusive
`-10,20-23`	integers 1 through 10, and integers 20 through 23, inclusive
`80,1023,90-100,12`	integers 80, 1023, and 12; and integers 90 through 100, inclusive
`-`	integers 1 through 65535

This parameter was put into effect in 1.2.18, 1.4.8, and 1.6.1

descr : string

A description of this preference (shown as tooltip)

range : string (DEPRECATED)

See default
DEPRECATED: This parameter is removed in 1.2.18, 1.4.8, and 1.6.1. Use the default parameter instead.

max : number

The maximum integer value in a range. This prevents a range string entry that exceeds this value. For example, a max of 15 causes an error message for range string 10-20,30.