11.6. Functions For New Protocols And Dissectors

The classes and functions in this chapter allow Lua scripts to create new protocols for Wireshark. Proto protocol objects can have Pref preferences, ProtoField fields for filterable values that can be displayed in a details view tree, functions for dissecting the new protocol, and so on.

The dissection function can be hooked into existing protocol tables through DissectorTable so that the new protocol dissector function gets called by that protocol, and the new dissector can itself call on other, already existing protocol dissectors by retrieving and calling the Dissector object. A Proto dissector can also be used as a post-dissector, at the end of every frame’s dissection, or as a heuristic dissector.

11.6.1. Dissector

A refererence to a dissector, used to call a dissector against a packet or a part of it.

11.6.1.1. Dissector.get(name)

Obtains a dissector reference by name.

Arguments
name
The name of the dissector.
Returns

The Dissector reference if found, otherwise nil.

11.6.1.2. Dissector.list()

Gets a Lua array table of all registered Dissector names.

Note: This is an expensive operation, and should only be used for troubleshooting.

Since: 1.11.3

Returns

The array table of registered dissector names.

11.6.1.3. dissector:call(tvb, pinfo, tree)

Calls a dissector against a given packet (or part of it).

Arguments
tvb
The buffer to dissect.
pinfo
The packet info.
tree
The tree on which to add the protocol items.
Returns

Number of bytes dissected. Note that some dissectors always return number of bytes in incoming buffer, so be aware.

11.6.1.4. dissector:__call(tvb, pinfo, tree)

Calls a dissector against a given packet (or part of it).

Arguments
tvb
The buffer to dissect.
pinfo
The packet info.
tree
The tree on which to add the protocol items.

11.6.1.5. dissector:__tostring()

Gets the Dissector’s protocol short name.

Returns

A string of the protocol’s short name.

11.6.2. DissectorTable

A table of subdissectors of a particular protocol (e.g. TCP subdissectors like http, smtp, sip are added to table "tcp.port").

Useful to add more dissectors to a table so that they appear in the “Decode As…​” dialog.

11.6.2.1. DissectorTable.new(tablename, [uiname], [type], [base], [proto])

Creates a new DissectorTable for your dissector’s use.

Arguments
tablename
The short name of the table. Use lower-case alphanumeric, dot, and/or underscores (e.g., "ansi_map.tele_id" or "udp.port").
uiname (optional)
The name of the table in the user interface. Defaults to the name given in tablename, but can be any string.
type (optional)
One of ftypes.UINT8, ftypes.UINT16, ftypes.UINT24, ftypes.UINT32, or ftypes.STRING. Defaults to ftypes.UINT32.
base (optional)
One of base.NONE, base.DEC, base.HEX, base.OCT, base.DEC_HEX or base.HEX_DEC. Defaults to base.DEC.
proto (optional)
The Proto object that uses this dissector table.
Returns

The newly created DissectorTable.

11.6.2.2. DissectorTable.list()

Gets a Lua array table of all DissectorTable names - i.e., the string names you can use for the first argument to DissectorTable.get().

Note: This is an expensive operation, and should only be used for troubleshooting.

Since: 1.11.3

Returns

The array table of registered DissectorTable names.

11.6.2.3. DissectorTable.heuristic_list()

Gets a Lua array table of all heuristic list names - i.e., the string names you can use for the first argument in Proto:register_heuristic().

Note: This is an expensive operation, and should only be used for troubleshooting.

Since: 1.11.3

Returns

The array table of registered heuristic list names

11.6.2.4. DissectorTable.try_heuristics(listname, tvb, pinfo, tree)

Try all the dissectors in a given heuristic dissector table.

Arguments
listname
The name of the heuristic dissector.
tvb
The buffer to dissect.
pinfo
The packet info.
tree
The tree on which to add the protocol items.
Returns

True if the packet was recognized by the sub-dissector (stop dissection here).

11.6.2.5. DissectorTable.get(tablename)

Obtain a reference to an existing dissector table.

Arguments
tablename
The short name of the table.
Returns

The DissectorTable reference if found, otherwise nil.

11.6.2.6. dissectortable:add(pattern, dissector)

Add a Proto with a dissector function or a Dissector object to the dissector table.

Arguments
pattern
The pattern to match (either an integer, a integer range or a string depending on the table’s type).
dissector
The dissector to add (either a Proto or a Dissector).

11.6.2.7. dissectortable:set(pattern, dissector)

Clear all existing dissectors from a table and add a new dissector or a range of new dissectors.

Since: 1.11.3

Arguments
pattern
The pattern to match (either an integer, a integer range or a string depending on the table’s type).
dissector
The dissector to add (either a Proto or a Dissector).

11.6.2.8. dissectortable:remove(pattern, dissector)

Remove a dissector or a range of dissectors from a table.

Arguments
pattern
The pattern to match (either an integer, a integer range or a string depending on the table’s type).
dissector
The dissector to remove (either a Proto or a Dissector).

11.6.2.9. dissectortable:remove_all(dissector)

Remove all dissectors from a table.

Since: 1.11.3

Arguments
dissector
The dissector to remove (either a Proto or a Dissector).

11.6.2.10. dissectortable:try(pattern, tvb, pinfo, tree)

Try to call a dissector from a table.

Arguments
pattern
The pattern to be matched (either an integer or a string depending on the table’s type).
tvb
The Tvb to dissect.
pinfo
The packet’s Pinfo.
tree
The TreeItem on which to add the protocol items.
Returns

Number of bytes dissected. Note that some dissectors always return number of bytes in incoming buffer, so be aware.

11.6.2.11. dissectortable:get_dissector(pattern)

Try to obtain a dissector from a table.

Arguments
pattern
The pattern to be matched (either an integer or a string depending on the table’s type).
Returns

The Dissector handle if found, otherwise nil

11.6.2.12. dissectortable:add_for_decode_as(proto)

Add the given Proto to the “Decode as…​” list for this DissectorTable. The passed-in Proto object’s dissector() function is used for dissecting.

Since: 1.99.1

Arguments
proto
The Proto to add.

11.6.2.13. dissectortable:__tostring()

Gets some debug information about the DissectorTable.

Returns

A string of debug information about the DissectorTable.

11.6.3. Pref

A preference of a Proto.

11.6.3.1. Pref.bool(label, default, descr)

Creates a boolean preference to be added to a Proto.prefs Lua table.

11.6.3.2. Example

    -- create a Boolean preference named "bar" for Foo Protocol
    -- (assuming Foo doesn't already have a preference named "bar")
    proto_foo.prefs.bar = Pref.bool( "Bar", true, "Baz and all the rest" )
Arguments
label
The Label (text in the right side of the preference input) for this preference.
default
The default value for this preference.
descr
A description of this preference.

11.6.3.3. Pref.uint(label, default, descr)

Creates an (unsigned) integer preference to be added to a Proto.prefs Lua table.

Arguments
label
The Label (text in the right side of the preference input) for this preference.
default
The default value for this preference.
descr
A description of what this preference is.

11.6.3.4. Pref.string(label, default, descr)

Creates a string preference to be added to a Proto.prefs Lua table.

Arguments
label
The Label (text in the right side of the preference input) for this preference.
default
The default value for this preference.
descr
A description of what this preference is.

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

Creates an enum preference to be added to a Proto.prefs Lua table.

11.6.3.6. Example:

    local OUTPUT_OFF        = 0
    local OUTPUT_DEBUG      = 1
    local OUTPUT_INFO       = 2
    local OUTPUT_WARN       = 3
    local OUTPUT_ERROR      = 4

    local output_tab = {
            { 1, "Off"              , OUTPUT_OFF },
            { 2, "Debug"            , OUTPUT_DEBUG },
            { 3, "Information"      , OUTPUT_INFO },
            { 4, "Warning"          , OUTPUT_WARN },
            { 5, "Error"            , OUTPUT_ERROR },
    }

    -- Create enum preference that shows as Combo Box under
    -- Foo Protocol's preferences
    proto_foo.prefs.outputlevel = Pref.enum(
            "Output Level",                 -- label
            OUTPUT_INFO,                    -- default value
            "Verbosity of log output",      -- description
            output_tab,                     -- enum table
            false                           -- show as combo box
    )

    -- Then, we can query the value of the selected preference.
    -- This line prints "Output Level: 3" assuming the selected
    -- output level is _INFO.
    debug( "Output Level: " .. proto_foo.prefs.outputlevel )
Arguments
label
The Label (text in the right side of the preference input) for this preference.
default
The default value for this preference.
descr
A description of what this preference is.
enum
An enum Lua table.
radio
Radio button (true) or Combobox (false).

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

Creates a range (numeric text entry) preference to be added to a Proto.prefs Lua table.

Arguments
label
The Label (text in the right side of the preference input) for this preference.
default
The default value for this preference, e.g., "53", "10-30", or "10-30,53,55,100-120".
descr
A description of what this preference is.
max
The maximum value.

11.6.3.8. Pref.statictext(label, descr)

Creates a static text string to be added to a Proto.prefs Lua table.

Arguments
label
The static text.
descr
The static text description.

11.6.4. Prefs

The table of preferences of a protocol.

11.6.4.1. prefs:__newindex(name, pref)

Creates a new preference.

Arguments
name
The abbreviation of this preference.
pref
A valid but still unassigned Pref object.
Errors
  • Unknown Pref type

11.6.4.2. prefs:__index(name)

Get the value of a preference setting.

11.6.4.3. Example

    -- print the value of Foo's preference named "bar"
    debug( "bar = " .. proto_foo.prefs.bar )
Arguments
name
The abbreviation of this preference.
Returns

The current value of the preference.

Errors
  • Unknown Pref type

11.6.5. Proto

A new protocol in Wireshark. Protocols have several uses. The main one is to dissect a protocol, but they can also be dummies used to register preferences for other purposes.

11.6.5.1. Proto.new(name, desc)

Creates a new Proto object.

Arguments
name
The name of the protocol.
desc
A Long Text description of the protocol (usually lowercase).
Returns

The newly created Proto object.

11.6.5.2. proto:__call(name, desc)

Creates a Proto object.

Arguments
name
The name of the protocol.
desc
A Long Text description of the protocol (usually lowercase).
Returns

The new Proto object.

11.6.5.3. proto:register_heuristic(listname, func)

Registers a heuristic dissector function for this Proto protocol, for the given heuristic list name.

When later called, the passed-in function will be given:

  1. A Tvb object
  2. A Pinfo object
  3. A TreeItem object

The function must return true if the payload is for it, else false.

The function should perform as much verification as possible to ensure the payload is for it, and dissect the packet (including setting TreeItem info and such) only if the payload is for it, before returning true or false.

Since version 1.99.1, this function also accepts a Dissector object as the second argument, to allow re-using the same Lua code as the function proto.dissector(…​). In this case, the Dissector must return a Lua number of the number of bytes consumed/parsed: if 0 is returned, it will be treated the same as a false return for the heuristic; if a positive or negative number is returned, then the it will be treated the same as a true return for the heuristic, meaning the packet is for this protocol and no other heuristic will be tried.

Since: 1.11.3

Arguments
listname
The heuristic list name this function is a heuristic for (e.g., "udp" or "infiniband.payload").
func
A Lua function that will be invoked for heuristic dissection.

11.6.5.4. proto.dissector

Mode: Retrieve or assign.

The protocol’s dissector, a function you define.

When later called, the function will be given:

  1. A Tvb object
  2. A Pinfo object
  3. A TreeItem object

11.6.5.5. proto.prefs

Mode: Retrieve only.

The preferences of this dissector.

11.6.5.6. proto.prefs_changed

Mode: Assign only.

The preferences changed routine of this dissector, a Lua function you define.

11.6.5.7. proto.init

Mode: Assign only.

The init routine of this dissector, a function you define.

The called init function is passed no arguments.

11.6.5.8. proto.name

Mode: Retrieve only.

The name given to this dissector.

11.6.5.9. proto.description

Mode: Retrieve only.

The description given to this dissector.

11.6.5.10. proto.fields

Mode: Retrieve or assign.

The `ProtoField`s Lua table of this dissector.

11.6.5.11. proto.experts

Mode: Retrieve or assign.

The expert info Lua table of this Proto.

Since: 1.11.3

11.6.6. ProtoExpert

A Protocol expert info field, to be used when adding items to the dissection tree.

Since: 1.11.3

11.6.6.1. ProtoExpert.new(abbr, text, group, severity)

Creates a new ProtoExpert object to be used for a protocol’s expert information notices.

Since: 1.11.3

Arguments
abbr
Filter name of the expert info field (the string that is used in filters).
text
The default text of the expert field.
group
Expert group type: one of: expert.group.CHECKSUM, expert.group.SEQUENCE, expert.group.RESPONSE_CODE, expert.group.REQUEST_CODE, expert.group.UNDECODED, expert.group.REASSEMBLE, expert.group.MALFORMED, expert.group.DEBUG, expert.group.PROTOCOL, expert.group.SECURITY, expert.group.COMMENTS_GROUP or expert.group.DECRYPTION.
severity
Expert severity type: one of: expert.severity.COMMENT, expert.severity.CHAT, expert.severity.NOTE, expert.severity.WARN, or expert.severity.ERROR.
Returns

The newly created ProtoExpert object.

11.6.6.2. protoexpert:__tostring()

Returns a string with debugging information about a ProtoExpert object.

Since: 1.11.3

11.6.7. ProtoField

A Protocol field (to be used when adding items to the dissection tree).

11.6.7.1. ProtoField.new(name, abbr, type, [valuestring], [base], [mask], [descr])

Creates a new ProtoField object to be used for a protocol field.

Arguments
name
Actual name of the field (the string that appears in the tree).
abbr
Filter name of the field (the string that is used in filters).
type
Field Type: one of: ftypes.BOOLEAN, ftypes.CHAR, ftypes.UINT8, ftypes.UINT16, ftypes.UINT24, ftypes.UINT32, ftypes.UINT64, ftypes.INT8, ftypes.INT16, ftypes.INT24, ftypes.INT32, ftypes.INT64, ftypes.FLOAT, ftypes.DOUBLE , ftypes.ABSOLUTE_TIME, ftypes.RELATIVE_TIME, ftypes.STRING, ftypes.STRINGZ, ftypes.UINT_STRING, ftypes.ETHER, ftypes.BYTES, ftypes.UINT_BYTES, ftypes.IPv4, ftypes.IPv6, ftypes.IPXNET, ftypes.FRAMENUM, ftypes.PCRE, ftypes.GUID, ftypes.OID, ftypes.PROTOCOL, ftypes.REL_OID, ftypes.SYSTEM_ID, ftypes.EUI64 or ftypes.NONE.
valuestring (optional)
A table containing the text that corresponds to the values, or a table containing tables of range string values that corresponds to the values ({min, max, "string"}) if the base is base.RANGE_STRING, or a table containing unit name for the values if base is base.UNIT_STRING, or one of frametype.NONE, frametype.REQUEST, frametype.RESPONSE, frametype.ACK or frametype.DUP_ACK if field type is ftypes.FRAMENUM.
base (optional)
The representation, one of: base.NONE, base.DEC, base.HEX, base.OCT, base.DEC_HEX, base.HEX_DEC, base.UNIT_STRING or base.RANGE_STRING.
mask (optional)
The bitmask to be used.
descr (optional)
The description of the field.
Returns

The newly created ProtoField object.

11.6.7.2. ProtoField.char(abbr, [name], [base], [valuestring], [mask], [desc])

Creates a ProtoField of an 8-bit ASCII character.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
base (optional)
One of base.NONE, base.HEX, base.OCT or base.RANGE_STRING.
valuestring (optional)
A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is base.RANGE_STRING.
mask (optional)
Integer mask of this field.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.3. ProtoField.uint8(abbr, [name], [base], [valuestring], [mask], [desc])

Creates a ProtoField of an unsigned 8-bit integer (i.e., a byte).

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
base (optional)
One of base.DEC, base.HEX or base.OCT, base.DEC_HEX, base.HEX_DEC, base.UNIT_STRING or base.RANGE_STRING.
valuestring (optional)
A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is base.RANGE_STRING, or a table containing the unit name for the values if base is base.UNIT_STRING.
mask (optional)
Integer mask of this field.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.4. ProtoField.uint16(abbr, [name], [base], [valuestring], [mask], [desc])

Creates a ProtoField of an unsigned 16-bit integer.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
base (optional)
One of base.DEC, base.HEX, base.OCT, base.DEC_HEX, base.HEX_DEC, base.UNIT_STRING or base.RANGE_STRING.
valuestring (optional)
A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is base.RANGE_STRING, or a table containing unit name for the values if base is base.UNIT_STRING.
mask (optional)
Integer mask of this field.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.5. ProtoField.uint24(abbr, [name], [base], [valuestring], [mask], [desc])

Creates a ProtoField of an unsigned 24-bit integer.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
base (optional)
One of base.DEC, base.HEX, base.OCT, base.DEC_HEX, base.HEX_DEC, base.UNIT_STRING, or base.RANGE_STRING.
valuestring (optional)
A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is base.RANGE_STRING, or a table containing the unit name for the values if base is base.UNIT_STRING.
mask (optional)
Integer mask of this field.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.6. ProtoField.uint32(abbr, [name], [base], [valuestring], [mask], [desc])

Creates a ProtoField of an unsigned 32-bit integer.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
base (optional)
One of base.DEC, base.HEX, base.OCT, base.DEC_HEX, base.HEX_DEC, base.UNIT_STRING, or base.RANGE_STRING.
valuestring (optional)
A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is base.RANGE_STRING, or a table containing the unit name for the values if base is base.UNIT_STRING.
mask (optional)
Integer mask of this field.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.7. ProtoField.uint64(abbr, [name], [base], [valuestring], [mask], [desc])

Creates a ProtoField of an unsigned 64-bit integer.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
base (optional)
One of base.DEC, base.HEX, base.OCT, base.DEC_HEX, base.HEX_DEC, base.UNIT_STRING, or base.RANGE_STRING.
valuestring (optional)
A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is base.RANGE_STRING, or a table containing the unit name for the values if base is base.UNIT_STRING.
mask (optional)
Integer mask of this field.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.8. ProtoField.int8(abbr, [name], [base], [valuestring], [mask], [desc])

Creates a ProtoField of a signed 8-bit integer (i.e., a byte).

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
base (optional)
One of base.DEC, base.UNIT_STRING, or base.RANGE_STRING.
valuestring (optional)
A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is base.RANGE_STRING, or a table containing unit name for the values if base is base.UNIT_STRING.
mask (optional)
Integer mask of this field.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.9. ProtoField.int16(abbr, [name], [base], [valuestring], [mask], [desc])

Creates a ProtoField of a signed 16-bit integer.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
base (optional)
One of base.DEC, base.UNIT_STRING, or base.RANGE_STRING.
valuestring (optional)
A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is base.RANGE_STRING, or a table containing unit name for the values if base is base.UNIT_STRING.
mask (optional)
Integer mask of this field.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.10. ProtoField.int24(abbr, [name], [base], [valuestring], [mask], [desc])

Creates a ProtoField of a signed 24-bit integer.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
base (optional)
One of base.DEC, base.UNIT_STRING, or base.RANGE_STRING.
valuestring (optional)
A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is base.RANGE_STRING, or a table containing unit name for the values if base is base.UNIT_STRING.
mask (optional)
Integer mask of this field.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.11. ProtoField.int32(abbr, [name], [base], [valuestring], [mask], [desc])

Creates a ProtoField of a signed 32-bit integer.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
base (optional)
One of base.DEC, base.UNIT_STRING, or base.RANGE_STRING.
valuestring (optional)
A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is base.RANGE_STRING, or a table containing unit name for the values if base is base.UNIT_STRING.
mask (optional)
Integer mask of this field.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.12. ProtoField.int64(abbr, [name], [base], [valuestring], [mask], [desc])

Creates a ProtoField of a signed 64-bit integer.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
base (optional)
One of base.DEC, base.UNIT_STRING, or`base.RANGE_STRING`.
valuestring (optional)
A table containing the text that corresponds to the values, or a table containing tables of range string values that correspond to the values ({min, max, "string"}) if the base is base.RANGE_STRING, or a table containing unit name for the values if base is base.UNIT_STRING.
mask (optional)
Integer mask of this field.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.13. ProtoField.framenum(abbr, [name], [base], [frametype], [mask], [desc])

Creates a ProtoField for a frame number (for hyperlinks between frames).

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
base (optional)
Only base.NONE is supported for framenum.
frametype (optional)
One of frametype.NONE, frametype.REQUEST, frametype.RESPONSE, frametype.ACK or frametype.DUP_ACK.
mask (optional)
Integer mask of this field, which must be 0 for framenum.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.14. ProtoField.bool(abbr, [name], [display], [valuestring], [mask], [desc])

Creates a ProtoField for a boolean true/false value.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
display (optional)
How wide the parent bitfield is (base.NONE is used for NULL-value).
valuestring (optional)
A table containing the text that corresponds to the values.
mask (optional)
Integer mask of this field.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.15. ProtoField.absolute_time(abbr, [name], [base], [desc])

Creates a ProtoField of a time_t structure value.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
base (optional)
One of base.LOCAL, base.UTC or base.DOY_UTC.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.16. ProtoField.relative_time(abbr, [name], [desc])

Creates a ProtoField of a time_t structure value.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.17. ProtoField.float(abbr, [name], [valuestring], [desc])

Creates a ProtoField of a floating point number (4 bytes).

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
valuestring (optional)
A table containing unit name for the values.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.18. ProtoField.double(abbr, [name], [valuestring], [desc])

Creates a ProtoField of a double-precision floating point (8 bytes).

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
valuestring (optional)
A table containing unit name for the values.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.19. ProtoField.string(abbr, [name], [display], [desc])

Creates a ProtoField of a string value.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
display (optional)
One of base.ASCII or base.UNICODE.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.20. ProtoField.stringz(abbr, [name], [display], [desc])

Creates a ProtoField of a zero-terminated string value.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
display (optional)
One of base.ASCII or base.UNICODE.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.21. ProtoField.bytes(abbr, [name], [display], [desc])

Creates a ProtoField for an arbitrary number of bytes.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
display (optional)
One of base.NONE, base.DOT, base.DASH, base.COLON or base.SPACE.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.22. ProtoField.ubytes(abbr, [name], [display], [desc])

Creates a ProtoField for an arbitrary number of unsigned bytes.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
display (optional)
One of base.NONE, base.DOT, base.DASH, base.COLON or base.SPACE.
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.23. ProtoField.none(abbr, [name], [desc])

Creates a ProtoField of an unstructured type.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.24. ProtoField.ipv4(abbr, [name], [desc])

Creates a ProtoField of an IPv4 address (4 bytes).

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.25. ProtoField.ipv6(abbr, [name], [desc])

Creates a ProtoField of an IPv6 address (16 bytes).

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.26. ProtoField.ether(abbr, [name], [desc])

Creates a ProtoField of an Ethernet address (6 bytes).

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.27. ProtoField.guid(abbr, [name], [desc])

Creates a ProtoField for a Globally Unique IDentifier (GUID).

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.28. ProtoField.oid(abbr, [name], [desc])

Creates a ProtoField for an ASN.1 Organizational IDentified (OID).

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.29. ProtoField.protocol(abbr, [name], [desc])

Creates a ProtoField for a sub-protocol. Since 1.99.9.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.30. ProtoField.rel_oid(abbr, [name], [desc])

Creates a ProtoField for an ASN.1 Relative-OID.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.31. ProtoField.systemid(abbr, [name], [desc])

Creates a ProtoField for an OSI System ID.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.32. ProtoField.eui64(abbr, [name], [desc])

Creates a ProtoField for an EUI64.

Arguments
abbr
Abbreviated name of the field (the string used in filters).
name (optional)
Actual name of the field (the string that appears in the tree).
desc (optional)
Description of the field.
Returns

A ProtoField object to be added to a table set to the Proto.fields attribute.

11.6.7.33. protofield:__tostring()

Returns a string with info about a protofield (for debugging purposes).

11.6.8. Global Functions

11.6.8.1. register_postdissector(proto, [allfields])

Make a Proto protocol (with a dissector function) a post-dissector. It will be called for every frame after dissection.

Arguments
proto
The protocol to be used as post-dissector.
allfields (optional)
Whether to generate all fields. Note: This impacts performance (default=false).

11.6.8.2. dissect_tcp_pdus(tvb, tree, min_header_size, get_len_func, dissect_func, [desegment])

Make the TCP-layer invoke the given Lua dissection function for each PDU in the TCP segment, of the length returned by the given get_len_func function.

This function is useful for protocols that run over TCP and that are either a fixed length always, or have a minimum size and have a length field encoded within that minimum portion that identifies their full length. For such protocols, their protocol dissector function can invoke this dissect_tcp_pdus() function to make it easier to handle dissecting their protocol’s messages (i.e., their protocol data unit (PDU)). This function shouild not be used for protocols whose PDU length cannot be determined from a fixed minimum portion, such as HTTP or Telnet.

Since: 1.99.2

Arguments
tvb
The Tvb buffer to dissect PDUs from.
tree
The Tvb buffer to dissect PDUs from.
min_header_size
The number of bytes in the fixed-length part of the PDU.
get_len_func
A Lua function that will be called for each PDU, to determine the full length of the PDU. The called function will be given (1) the Tvb object of the whole Tvb (possibly reassembled), (2) the Pinfo object, and (3) an offset number of the index of the first byte of the PDU (i.e., its first header byte). The Lua function must return a Lua number of the full length of the PDU.
dissect_func
A Lua function that will be called for each PDU, to dissect the PDU. The called function will be given (1) the Tvb object of the PDU’s Tvb (possibly reassembled), (2) the Pinfo object, and (3) the TreeItem object. The Lua function must return a Lua number of the number of bytes read/handled, which would typically be the Tvb:len().
desegment (optional)
Whether to reassemble PDUs crossing TCP segment boundaries or not. (default=true)