將信息添加到Dissection tree

TreeItem

<lua_class_TreeItem，TreeItem>> s表示Wireshark 的數據包詳細信息窗格和Tshark的數據包詳細信息視圖中的信息。A TreeItem表示樹中的一個節點，該節點也可以是子樹并具有子級列表。子樹的子級具有零個或多個同級子弟，它們是同一TreeItem子樹的其他子級。

在解析、啟發式解析和解析后過程中，根<LUA_CLASS_TreeItem，TreeItem>>將作為函數回調的第三個參數(例如mypro.dissector(twbuf，pktinfo，root))傳遞給dissectors。

在某些情況下，為了提高性能，并未真正將樹添加到其中。例如，對于當前未在Wireshark的可見窗格中顯示/選擇的數據包，或者如果未使用-V開關調用Tshark。但是，仍然可以調用“add”類型的TreeItem函數，并且仍然返回TreeItem對象-但是信息并沒有真正添加到樹中。因此，您通常不需要擔心是否存在真正的樹。如果出于某種原因需要知道，可以使用TreeItem.Visible屬性getter來檢索狀態。

treeitem:add_packet_field(protofield, [tvbrange], encoding, [label])

將給定ProtoField對象的新子樹添加到此樹項目中，并返回新子TreeItem。

與TreeItem：add()和TreeItem：add_le()不同，ProtoField參數不是可選的，并且不能是Proto對象。相反，此函數始終使用ProtoField來確定要從傳入的TvbRange中提取的字段類型，突出顯示GUI(如果有GUI)的Packet Bytes窗格中的相關字節，依此類推。如果沒有給出TvbRange，則不會突出顯示任何字節，并且無法確定字段的值；在這種情況下，必須定義/創建ProtoField以不具有長度，否則將發生錯誤。但是，出于向后兼容性的原因，仍然必須給出編碼參數。

與TreeItem：add()和TreeItem：add_le()不同，該函數通過將編碼參數設置為ENC_BIG_ENDIAN或ENC_LITLE_ENDIAN，同時執行大端和小端解碼。

此函數的簽名：

 tree_item:add_packet_field(proto_field [,tvbrange], encoding, ...)

在Wireshark版本1.11.3中，此函數已更改為不僅僅返回新子TreeItem。子函數是第一個返回值，因此函數鏈接仍將像以前一樣工作；但它現在還返回提取的字段的值(例如，Number、UInt64、Address等)。如果無法從TvbRange中提取該值，則仍返回子TreeItem，但第二個返回值為空。

Wireshark版本1.11.3中添加到此函數的另一個新功能是，對于基于ASCII和類似的字符串編碼，能夠從`TvbRange中的字符串編碼中提取本地編號ProtoField。例如，可以從包含ASCII字符串“123”的TvbRange中提取as ftyes.UINT32類型的ProtoField，并且它將在樹中以及該函數的第二個返回值中將ASCII正確解碼為數字123。為此，必須將該函數的編碼參數設置為適當的字符串enc_*值，與enc_string值按位或d(請參見init.lua)。ENC_STRING保證是唯一的位標志，因此也可以將其相加，而不是按位或。只能使用單字節ASCII數字字符串編碼類型，如ENC_ASCII和ENC_UTF_8。

例如，假設名為“TVB”的TVB包含字符串“123”：

 -- this is done earlier in the script
     local myfield = ProtoField.new("Transaction ID", "myproto.trans_id", ftypes.UINT16)

     -- this is done inside a dissector, post-dissector, or heuristic function
     -- child will be the created child tree, and value will be the number 123 or nil on failure
     local child, value = tree:add_packet_field(myfield, tvb:range(0,3), ENC_UTF_8 + ENC_STRING)

Arguments
protofield
The ProtoField field object to add to the tree.
tvbrange (optional)
The TvbRange of bytes in the packet this tree item covers/represents.
encoding
The field’s encoding in the TvbRange.
label (optional)
One or more strings to append to the created TreeItem.
Returns
The new child TreeItem, the field’s extracted value or nil, and offset or nil.

treeitem:add([protofield], [tvbrange], [value], [label])

將子項添加到此樹項，并返回新的子項TreeItem。
如果ProtoField表示數值(int、uint或Float)，則將其視為大端(網絡訂單)值。
此函數具有復雜的形式：‘treeitem：add([Protofield，][twbrange，]value]，Label)’，這樣，如果第一個參數是ProtoField或Proto，第二個參數是TvbRange，并且給出了第三個參數，則它是一個值；但如果第二個參數是非TvbRange，那么它就是值(而不是用‘nil’填充該參數，后者對此函數無效)。
如果第一個參數是非ProtoField和非Proto，則此參數可以是TvbRange或標簽，并且該值未使用。

例：

local proto_foo = Proto("foo", "Foo Protocol")
    proto_foo.fields.bytes = ProtoField.bytes("foo.bytes", "Byte array")
    proto_foo.fields.u16 = ProtoField.uint16("foo.u16", "Unsigned short", base.HEX)

    function proto_foo.dissector(buf, pinfo, tree)
            -- ignore packets less than 4 bytes long
            if buf:len() < 4 then return end

            -- ##############################################
            -- # Assume buf(0,4) == {0x00, 0x01, 0x00, 0x02}
            -- ##############################################

            local t = tree:add( proto_foo, buf() )

            -- Adds a byte array that shows as: "Byte array: 00010002"
            t:add( proto_foo.fields.bytes, buf(0,4) )

            -- Adds a byte array that shows as "Byte array: 313233"
            -- (the ASCII char code of each character in "123")
            t:add( proto_foo.fields.bytes, buf(0,4), "123" )

            -- Adds a tree item that shows as: "Unsigned short: 0x0001"
            t:add( proto_foo.fields.u16, buf(0,2) )

            -- Adds a tree item that shows as: "Unsigned short: 0x0064"
            t:add( proto_foo.fields.u16, buf(0,2), 100 )

            -- Adds a tree item that shows as: "Unsigned short: 0x0064 ( big endian )"
            t:add( proto_foo.fields.u16, buf(1,2), 100, nil, "(", nil, "big", 999, nil, "endian", nil, ")" )

            -- LITTLE ENDIAN: Adds a tree item that shows as: "Unsigned short: 0x0100"
            t:add_le( proto_foo.fields.u16, buf(0,2) )

            -- LITTLE ENDIAN: Adds a tree item that shows as: "Unsigned short: 0x6400"
            t:add_le( proto_foo.fields.u16, buf(0,2), 100 )

            -- LITTLE ENDIAN: Adds a tree item that shows as: "Unsigned short: 0x6400 ( little endian )"
            t:add_le( proto_foo.fields.u16, buf(1,2), 100, nil, "(", nil, "little", 999, nil, "endian", nil, ")" )
    end

    udp_table = DissectorTable.get("udp.port")
    udp_table:add(7777, proto_foo)

Arguments

protofield (optional)

The ProtoField field or Proto protocol object to add to the tree.

tvbrange (optional)

The TvbRange of bytes in the packet this tree item covers/represents.

value (optional)

The field’s value, instead of the ProtoField/Proto one.

label (optional)

One or more strings to use for the tree item label, instead of the ProtoField/Proto one.

Returns

The new child TreeItem.

treeitem:add_le([protofield], [tvbrange], [value], [label])

將子項添加到此樹項，并返回新的子項TreeItem。

如果ProtoField表示數值(int、uint或Float)，則將其視為大端(網絡訂單)值。

此函數具有復雜的形式：‘treeitem：add([Protofield，][twbrange，]value]，Label)’，這樣，如果第一個參數是ProtoField或Proto，第二個參數是TvbRange，并且給出了第三個參數，則它是一個值；但如果第二個參數是非TvbRange，那么它就是值(而不是用‘nil’填充該參數，后者對此函數無效)。如果第一個參數是非ProtoField和非Proto，則此參數可以是TvbRange或標簽，并且該值未使用。

參數

protofield (optional)

The ProtoField field or Proto protocol object to add to the tree.

tvbrange (optional)

The TvbRange of bytes in the packet this tree item covers/represents.

value (optional)

The field’s value, instead of the ProtoField/Proto one.

label (optional)

One or more strings to use for the tree item label, instead of the ProtoField/Proto one.

Returns

The new child TreeItem.

treeitem:set_text(text)

設置標簽的文本。

這過去不返回任何內容，但是從1.11.3開始，它返回相同的樹項以允許鏈接調用。

參數

text

The text to be used.

Returns

The same TreeItem.

treeitem:append_text(text)

將文本附加到標簽。

這過去不返回任何內容，但是從1.11.3開始，它返回相同的樹項以允許鏈接調用。

Arguments

text

The text to be appended.

Returns

The same TreeItem.

treeitem:add_expert_info([group], [severity], [text])

設置項目的專家標志，并將專家信息添加到數據包。

此功能不會為協議創建真正可過濾的專家信息。相反，您應該使用TreeItem.add_proto_Expert_info()。

注意：提供此函數只是為了向后兼容，不應在新的Lua代碼中使用。它可能會在未來被移除。您應該只使用TreeItem.add_proto_Expert_info()。

參數

group (optional)

One of PI_CHECKSUM, PI_SEQUENCE, PI_RESPONSE_CODE, PI_REQUEST_CODE, PI_UNDECODED, PI_REASSEMBLE, PI_MALFORMED or PI_DEBUG.

severity (optional)

One of PI_CHAT, PI_NOTE, PI_WARN, or PI_ERROR.

text (optional)

The text for the expert info display.

Returns

The same TreeItem.

treeitem:add_proto_expert_info(expert, [text])

設置樹項目的標志，并將專家信息添加到數據包。

Arguments

expert

The ProtoExpert object to add to the tree.

text (optional)

Text for the expert info display (default is to use the registered text).

Returns

The same TreeItem.

treeitem:add_tvb_expert_info(expert, tvb, [text])

設置樹項目的標志，并將專家信息添加到與數據包中的TVB或TvbRange字節相關聯的數據包。

參數

expert

The ProtoExpert object to add to the tree.

tvb

The Tvb or TvbRange object bytes to associate the expert info with.

text (optional)

Text for the expert info display (default is to use the registered text).

Returns

The same TreeItem.

treeitem:set_generated([bool])

將TreeItem標記為生成的字段(具有推斷但不包含在數據包中的數據)。

Arguments

bool (optional)

A Lua boolean, which if true sets the TreeItem generated flag, else clears it (default=true)

Returns

The same TreeItem.
這過去不返回任何內容，但是從1.11.3開始，它返回相同的樹項以允許鏈接調用。

treeitem:set_hidden([bool])

將TreeItem標記為隱藏字段(既不在篩選器中顯示，也不在篩選器中使用)。棄用。

這過去不返回任何內容，但是從1.11.3開始，它返回相同的樹項以允許鏈接調用。

Arguments

bool (optional)

A Lua boolean, which if true sets the TreeItem hidden flag, else clears it. Default is true.

Returns

The same TreeItem.

treeitem:set_len(len)

在TVB內設置TreeItem的長度，在創建之后。

這過去不返回任何內容，但是從1.11.3開始，它返回相同的樹項以允許鏈接調用。

Arguments

len

The length to be used.

Returns

The same TreeItem.

treeitem:referenced(protofield)

檢查篩選器/點擊/UI是否引用了ProtoField或分析器。

如果此函數返回false，則表示不需要剖析該字段(或分析器)，可以安全地跳過該字段。通過跳過一個字段而不是分析它，分析器通常會運行得更快，因為Wireshark在不需要該字段時不會執行額外的分析工作。

您可以將其與TreeItem.Visible屬性結合使用。當TreeItem可見時，此函數將始終返回TRUE。當該字段不可見且該字段未被引用時，您可以通過不解剖該字段來加快解析速度，因為顯示或過濾不需要該字段。

此函數接受一個參數，該參數可以是ProtoField或分析器。當您需要決定是否調用子分析器時，分析器窗體非常有用。

Arguments

protofield

The ProtoField or Dissector to check if referenced.

Returns

A boolean indicating if the ProtoField/Dissector is referenced

treeitem:__tostring()

返回有關TreeItem的字符串調試信息。

treeitem.text

Mode: Retrieve or assign.

Set/get the TreeItem display string (string).

For the getter, if the TreeItem has no display string, then nil is returned.

treeitem.visible

Mode: Retrieve only.

Get the TreeItem subtree visibility status (boolean).

treeitem.generated

Mode: Retrieve or assign.

Set/get the TreeItem generated state (boolean).

treeitem.hidden

Mode: Retrieve or assign.

Set/get TreeItem hidden state (boolean).

treeitem.len

Mode: Retrieve or assign.

Set/get TreeItem length inside tvb, after it has already been created.