自定義文件格式讀寫

CaptureInfo

一個CaptureInfo對象，由FileHandler回調函數read_open()、read()、ek_read()、seq_read_close()和read_close()作為參數傳遞給Lua。此對象表示正在讀取到Wireshark/Tshark中的捕獲文件數據和元數據(關于捕獲文件的數據)。

該對象的字段可以在基于讀取的函數回調期間由Lua寫入。換句話說，當調用Lua插件的FileHandler.read_open()函數時，CaptureInfo對象將作為參數之一傳入，其字段應該由Lua代碼寫入以告知Wireshark有關捕獲的信息。

captureinfo:__tostring()

為CaptureInfo生成調試信息字符串。

Return

調試信息字符串。

captureinfo.encap

Mode：檢索或分配。

整個文件的數據包封裝類型。

有關可用的類型，請參見init.lua中的WTAP_encaps。如果數據包可以有不同的類型，則設置為WTAP_encaps.PER_PACKET，然后在read()/Seek_Read()期間為每個數據包設置FrameInfo.encap。

captureinfo.time_precision

模式：檢索或分配。

文件中數據包時間戳的精度。

有關可用的精度，請參見init.lua中的wtap_file_tsprec。

captureinfo.snapshot_length

模式：檢索或分配。

可以記錄的最大數據包長度。

將其設置為0表示未知精度。

captureinfo.comment

Mode: Retrieve or assign.
整個捕獲文件的字符串注釋，如果沒有任何comment，則為空。

captureinfo.hardware

Mode: Retrieve or assign.
包含用于創建捕獲的硬件描述的字符串，如果沒有硬件字符串，則為空。

captureinfo.os

模式：檢索或分配。

包含用于創建捕獲的操作系統名稱的字符串，如果沒有操作系統字符串，則為空。

captureinfo.user_app

模式：檢索或分配。
包含用于創建捕獲的應用程序名稱的字符串，如果沒有USER_APP字符串，則為空。

captureinfo.hosts

模式：僅分配。

設置解析的IP到主機名信息。

值集必須是包含兩個鍵名稱的LUA表：IPv4_ADDRESSES和IPv6_ADDRESSES。這些名稱中的每一個的值本身就是鍵表的陣列表，使得內部表具有設置為原始4字節或16字節IP地址Lua字符串的鍵地址，以及設置為解析名稱的名稱。

例如，如果捕獲文件將一個解析的IPv4地址1.2.3.4標識為foo.com，則必須將CaptureInfo.hosts設置為以下表：

{ ipv4_addresses = { { addr = "\01\02\03\04", name = "foo.com" } } }

注意，IPv4_Addresses和/或IPv6_Addresses表可以為空或為零。

captureinfo.private_table

模式：檢索或分配。

此文件唯一的私有Lua值。

PRIVATE_TABLE是您使用自己的Lua表設置/獲取的字段。這是為了使Lua腳本可以保存每個文件的讀/寫狀態，因為可以同時打開和讀取多個文件。

例如，如果用戶發出了reload-file命令，或者Lua調用了reload()函數，則當前捕獲文件在打開新文件時仍處于打開狀態，因此Wireshark將在前一個捕獲文件沒有導致調用read_close()時調用read_open()；如果read_open()成功，則將緊跟在前一個文件(而不是剛剛打開的文件)的后面調用read_close()。因此，通過在read_open()函數中設置這個private_table，Lua腳本可以使用這個private_table來存儲特定于每個文件的值表，然后它可以在稍后返回到它的read()、Seek_read()和read_close()函數中。

CaptureInfoConst

一個CaptureInfoConst對象，作為FileHandler回調函數write_open()的參數傳遞給Lua。

此對象表示Wireshark/Tshark中當前捕獲的捕獲文件數據和元數據(有關捕獲文件的數據)。

此對象的字段在由WRITE_OPEN函數回調使用時是可讀的。換句話說，當調用Lua插件的FileHandler write_open函數時，CaptureInfoConst對象將作為參數之一傳入，并且它的字段應該由Lua代碼讀取，以獲得需要寫入的捕獲數據。

captureinfoconst:__tostring()

為CaptureInfoConst生成調試信息字符串。

Return

調試信息字符串。

captureinfoconst.type

Mode: Retrieve only.
The file type.

captureinfoconst.snapshot_length

模式：僅檢索。

實際記錄的最大數據包長度(與任何給定在線數據包的原始長度相比)。值0表示快照長度未知，或者整個文件沒有這樣的長度。

captureinfoconst.encap

模式：僅檢索。

整個文件的數據包封裝類型。

有關可用的類型，請參見init.lua中的WTAP_encaps。如果數據包在FrameInfo.Packet_encap中可以有不同的類型，則將其設置為WTAP_encaps.PER_PACKET，在這種情況下，每個幀都標識其類型。

captureinfoconst.comment

Mode: Retrieve or assign.

A comment for the whole capture file, if the wtap_presence_flags.COMMENTS was set in the presence flags; nil if there is no comment.

captureinfoconst.hardware

Mode: Retrieve only.

A string containing the description of the hardware used to create the capture, or nil if there is no hardware string.

captureinfoconst.os

Mode: Retrieve only.

A string containing the name of the operating system used to create the capture, or nil if there is no os string.

captureinfoconst.user_app

Mode: Retrieve only.

A string containing the name of the application used to create the capture, or nil if there is no user_app string.

captureinfoconst.hosts

模式：僅檢索。

IP到主機名的Lua表，包含兩個關鍵字名稱：IPv4_Addresses和IPv6_Addresses。這些名稱中的每一個的值本身就是鍵表的陣列表，使得內部表具有設置為原始4字節或16字節IP地址Lua字符串的鍵地址，以及設置為解析名稱的名稱。

例如，如果當前捕獲有一個解析的IPv4地址1.2.3.4到foo.com，則獲取CaptureInfoConst.hosts將獲得一個表，其中包括：

  { ipv4_addresses = { { addr = "\01\02\03\04", name = "foo.com" } }, ipv6_addresses = { } }

注意，IPv4_Addresses和/或IPv6_Addresses表可以為空，但它們不會為零。

captureinfoconst.private_table

模式：檢索或分配。

此文件唯一的私有Lua值。

PRIVATE_TABLE是您使用自己的Lua表設置/獲取的字段。這是為了使Lua腳本可以保存每個文件的讀/寫狀態，因為可以同時打開和讀取多個文件。

例如，如果兩個Lua腳本發出Dumper：new_for_current()調用，并且當前文件恰好使用腳本的編寫器，則Wireshark將調用write_open()，而前一個捕獲文件尚未調用write_close()。因此，通過在write_open()函數中設置這個private_table，Lua腳本可以使用這個private_table來存儲特定于每個文件的值表，稍后它可以將其返回到write()和write_close()函數中。

File

File對象，由FileHandler回調函數(例如READ_OPEN、READ、WRITE等)作為參數傳遞給Lua。它的行為類似于Lua io庫的file對象，在調用io.open()時返回，除了在本例中您不能調用file：close()、file：open()或file：setvbuf()，因為Wireshark/tshark管理文件的打開和關閉。您也不能在此對象上使用“io”庫本身，即不能執行io.read(file，4)。取而代之的是，將此File與調用其方法的面向對象樣式一起使用，即myfile：read(4)。(請參閱后面的示例)。

此對象的目的是隱藏Wireshark如何處理文件的內部復雜性，而是通過模仿io庫來提供熟悉的Lua接口。不能使用true/raw io文件的原因是，Wireshark在幕后執行許多操作，例如壓縮文件、寫入標準輸出或基于配置/命令執行各種其他操作。

當通過基于讀取的回調函數(如read_open()、read()和read_close())傳入File對象時，File對象的write()和flush()函數不可用，如果使用將引發錯誤。

當File對象通過基于寫入的回調函數(如write_open()、write()和write_close())傳入時，File對象的read()和lines()函數不可用，如果使用將引發錯誤。

注意：File對象的存儲/保存絕不應超出其傳入的回調函數的作用域。

 function myfilehandler.read_open(file, capture)
        local position = file:seek()

        -- read 24 bytes
        local line = file:read(24)

        -- do stuff

        -- it's not our file type, seek back (unnecessary but just to show it...)
        file:seek("set",position)

        -- return false because it's not our file type
        return false
    end

file:read()

讀取文件，類似于Lua的文件：read()。有關file：read()，請參閱Lua 5.x參考手冊。

file:seek()

在文件中查找，類似于Lua的文件：Seek()。請參閱Lua 5.x Ref手冊以了解FILE：SEEK()。

Returns

The current file cursor position as a number.

file:lines()

用于檢索ASCII文件行的Lua迭代器函數，類似于Lua的FILE：LINES()。參見LUA 5.x參考手冊了解FILE：LINES()。

file:write()

寫入文件，類似于Lua的文件：write()。有關file：write()的信息，請參閱Lua 5.x參考手冊。

file:__tostring()

為File對象生成調試信息字符串。

Returns

調試信息字符串。

file.compressed

模式：僅檢索。

文件是否壓縮。

有關可用的類型，請參見init.lua中的WTAP_encaps。如果數據包可以有不同的類型，則設置為WTAP_encaps.PER_PACKET，然后在read()/Seek_Read()期間為每個數據包設置FrameInfo.encap。

FileHandler

通過調用FileHandler.new(arg1，arg2，…)創建的FileHandler對象。?)。FileHandler對象允許您通過設置自己的READ_OPEN/READ或WRITE_OPEN/WRITE函數來創建文件格式讀取器和/或寫入器。

FileHandler.new(name, shortname, description, type)

創建新的 FileHandler

Arguments

name

文件類型的名稱，僅供顯示。例如，“wireshark-pcapng”

shortname

文件類型簡稱，在不同位置用作快捷方式。
例如，“pcapng”。
注意：該名稱不能已在使用中。

description

Descriptive text about this file format, for display purposes only

type

The type of FileHandler, “r”/“w”/“rw” for reader/writer/both, include “m” for magic, “s” for strong heuristic

Returns

The newly created FileHandler object

filehandler:__tostring()

Generates a string of debug info for the FileHandler

Returns

String of debug information.

Filehandler.read_open。

模式：僅分配。

Wireshark打開要讀取的文件時要調用的Lua函數。

稍后由Wireshark調用時，將給出Lua函數：

文件對象。
CaptureInfo對象。
設置為READ_OPEN字段的Lua函數的目的是檢查Wireshark正在打開的文件是否屬于該類型，例如，通過檢查幻數或嘗試解析文件中的記錄等。驗證的次數越多越好，因為Wireshark會嘗試所有文件讀取器，直到找到接受該文件的讀取器，因此接受不正確的文件會阻止其他文件讀取器讀取他們的文件。

如果文件是它的類型(它接受它)，則調用的Lua函數應該返回true，否則返回false。LUA函數還必須將File Offset位置(使用FILE：Seek())設置為其第一次調用read()時所希望的位置。

filehandler.read

模式：僅分配。

當Wireshark想要從文件中讀取數據包時要調用的Lua函數。

稍后由Wireshark調用時，將給出Lua函數：

• 文件對象
• CaptureInfo對象
• FrameInfo對象

設置為該讀取字段的Lua函數的目的是從文件中讀取下一個數據包，并使用FrameInfo.data=foo或FrameInfo：read_data(file，frame.caped_length)將解析/讀取的數據包設置到幀緩沖區中。

調用的Lua函數應該返回數據包開始處的文件偏移量/位置號，如果遇到錯誤，則返回false。文件偏移量將由Wireshark保存，并在稍后傳遞給SET SEEK_READ()Lua函數。

filehandler.seek_read

模式：僅分配。

當Wireshark要從文件中給定偏移量讀取數據包時要調用的Lua函數。

稍后由Wireshark調用時，將給出Lua函數：

• 文件對象
• CaptureInfo對象
• FrameInfo對象
• 先前由read()函數調用設置的文件偏移量

如果讀取成功，則調用的Lua函數應返回TRUE，如果遇到錯誤，則返回FALSE。從2.4.0開始，表示成功的數字也是可以接受的，這允許重用FileHandler：Read：

local function fh_read(file, capture, frame) ... end
    myfilehandler.read = fh_read

    function myfilehandler.seek_read(file, capture, frame, offset)
        if not file:seek("set", offset) then
            -- Seeking failed, return failure
            return false
        end

        -- Now try to read one frame
        return fh_read(file, capture, frame)
    end

filehandler.read_close

模式：僅分配。

當Wireshark想要完全關閉讀取的文件時要調用的Lua函數。

稍后由Wireshark調用時，將給出Lua函數：

• 文件對象
• CaptureInfo對象

沒有必要將此字段設置為Lua函數-可以在不這樣做的情況下注冊FileHandler-如果在關閉文件時腳本中有內存/狀態需要清除，則可以使用此字段。

filehandler.seq_read_close

模式：僅分配。

當Wireshark想要關閉順序讀取的文件時要調用的Lua函數。

稍后由Wireshark調用時，將給出Lua函數：

• 文件對象
• CaptureInfo對象

沒有必要將此字段設置為Lua函數-可以在不這樣做的情況下注冊FileHandler-如果在關閉文件以進行順序讀取部分時腳本中有內存/狀態需要清除，則可以使用此字段。在此之后，將不會再調用read()，只會調用Seek_Read()。

filehandler.can_write_encap

模式：僅分配。
當Wireshark想要寫入文件時要調用的Lua函數，方法是檢查此文件編寫器是否可以處理WTAP數據包封裝。

當稍后由Wireshark調用時，Lua函數將被賦予一個Lua編號，該編號與Lua WTAP_encaps表中的一個封裝相匹配。
這可能是WTAP_encap.PER_PACKET編號，這意味著捕獲包含多種封裝類型，如果文件讀取器可以在一個文件中處理多種封裝類型，則它應該僅返回TRUE。
然后將再次調用該函數，為文件中的每個封裝類型調用一次，以確保它可以寫入每個封裝類型。

如果Lua文件寫入器可以將給定類型的封裝寫入文件，則返回布爾值true，否則返回false。

filehandler.write_open

模式：僅分配。

Wireshark打開要寫入的文件時要調用的Lua函數。

稍后由Wireshark調用時，將給出Lua函數：

• 文件對象
• CaptureInfoConst對象

設置為WRITE_OPEN字段的Lua函數的用途類似于READ_OPEN回調函數：初始化將捕獲寫入文件所需的內容。例如，如果輸出文件格式有文件頭，則文件頭應該寫入此WRITE_OPEN函數中。

調用的Lua函數在成功時應返回TRUE，如果遇到錯誤則返回FALSE。

還要確保在從此函數返回true之前設置FileHandler.write(可能還有FileHandler.write_Finish)函數。

filehandler.write

模式：僅分配。
當Wireshark想要將數據包寫入文件時要調用的Lua函數。
稍后由Wireshark調用時，將給出Lua函數：

• 文件對象
• CaptureInfoConst對象

要寫入的當前幀/包的FrameInfoConst對象。
設置到該寫入字段的LUA函數的目的是將下一個包寫入文件。
調用的Lua函數在成功時應返回TRUE，如果遇到錯誤則返回FALSE。

filehandler.write_finish

模式：僅分配。

當Wireshark想要關閉寫入的文件時要調用的Lua函數。

稍后由Wireshark調用時，將給出Lua函數：

• 文件對象
• CaptureInfoConst對象

沒有必要將此字段設置為Lua函數-可以在不這樣做的情況下注冊FileHandler-如果在關閉文件時腳本中有內存/狀態需要清除，則可以使用此字段。

filehandler.type

模式：僅檢索。

內部文件類型。注冊FileHandler時，會自動使用新編號設置該值。

filehandler.extensions

模式：檢索或分配。
此文件類型通常使用的一個或多個以分號分隔的文件擴展名。
對于使用試探法確定文件類型的讀取器，Wireshark會先嘗試文件擴展名的讀取器，然后再嘗試其他讀取器。
但最終，Wireshark會嘗試所有文件讀取器以查找任何文件擴展名，直到找到一個可以接受該文件的讀取器。
對于編寫器，第一個擴展名用于建議默認文件擴展名。

filehandler.writing_must_seek

模式：檢索或分配。

如果寫入此文件格式時需要查找功能，則為true，否則為false。

寫出壓縮文件格式時，Wireshark將檢查這一點，因為無法對壓縮文件進行查找。通常，文件寫入器只需要能夠查找是否需要返回文件以更改某些內容，例如文件中較早的塊或文件長度值。

filehandler.writes_name_resolution

模式：檢索或分配。
如果文件格式支持名稱解析記錄，則為true，否則為false。

filehandler.supported_comment_types

模式：檢索或分配。
根據wap_comments表中的數字，設置為表示文件編寫器支持寫入的注釋類型的逐位或運算數字。

FrameInfo

一個FrameInfo對象，由FileHandler回調函數(例如，Read、Seek_Read等)作為參數傳遞給Lua。

該對象表示給定read/Seek_read/寫入幀的幀數據和元數據(關于幀/包的數據)。

此對象的字段在由讀取函數回調使用時為Write-to/Set，在由文件寫入函數回調使用時為Read-from/Get。
換句話說，當調用Lua插件的FileHandler read/Seek_read/etc函數時，FrameInfo對象將作為參數之一傳入，其字段應該根據從文件讀取的幀信息寫入/設置；而當調用Lua插件的FileHandler.write()函數時，傳入的FrameInfo對象應該有其字段read-from/get，以便將該幀信息寫入文件。

frameinfo:__tostring()

為FrameInfo生成調試信息字符串。
Return
調試信息字符串.

frameinfo:read_data(file, length)

告知Wireshark直接從給定文件讀取幀數據緩沖區中的長度字節。如果成功，則返回TRUE，否則返回FALSE。

Arguments

file
文件對象userdata，由Wireshark以前在基于讀取的回調中提供。
length
要在當前光標位置從文件中讀取的字節數。
length
TRUE如果成功，則ELSE返回FALSE以及錯誤號和字符串錯誤描述。

幀緩沖區數據的Lua字符串。

frameinfo.time

模式:檢索或分配。

數據包的時間戳作為一個NSTime對象。

注意:設置文件處理程序。
也可以將time_precision設置為適當的wtap_file_tsprec值。

同時將FileHandler.time_precision設置為適當的wtap_file_tsprec值。

frameinfo.data

模式：檢索或分配。
包含數據包的數據緩沖區。

frameinfo.rec_type

模式:檢索或分配。

包幀的記錄類型

參見init.lua中的 wtap_rec_types的值。

frameinfo.flags

模式:檢索或分配。

數據包幀的存在標志。

參見init.lua中的wtap_presence_flags獲取bit值。

frameinfo.captured_length

模式:檢索或分配。

捕獲的包長度，因此傳遞到FrameInfo.data字段的緩沖區長度。

frameinfo.original_length

Mode: Retrieve or assign.

The on-the-wire packet length, which may be longer than the captured_length.

frameinfo.encap

Mode: Retrieve or assign.
幀/數據包的數據包封裝類型(如果文件支持按數據包類型)。
請參閱init.lua中的WTAP_encaps，了解用作此字段值的可能數據包封裝類型。

frameinfo.comment

Mode: Retrieve or assign.
如果在存在標志中設置了WTAP_Presence_Flags.COMMENTS，則為數據包的字符串注釋；如果沒有注釋，則為空。

FrameInfoConst

一個常量FrameInfo對象，由FileHandler寫回調函數作為參數傳遞給Lua。
它具有與FrameInfo類似的屬性/屬性，但是字段只能讀取，而不能寫入。

frameinfoconst:__tostring()

Generates a string of debug info for the FrameInfo

Returns

String of debug information.

frameinfoconst:write_data(file, [length])

Tells Wireshark to write directly to given file from the frame data buffer, for length bytes. Returns true if succeeded, else false.

Arguments

file
The File object userdata, provided by Wireshark previously in a writing-based callback.

length (optional)

The number of bytes to write to the file at the current cursor position, or all if not supplied.

Returns

True if succeeded, else returns false along with the error number and string error description.

frameinfoconst.time

Mode: Retrieve only.

The packet timestamp as an NSTime object.

frameinfoconst.data

Mode: Retrieve only.

The data buffer containing the packet.

frameinfoconst.rec_type

Mode: Retrieve only.

The record type of the packet frame - see wtap_presence_flags in init.lua for values.

frameinfoconst.flags

Mode: Retrieve only.

The presence flags of the packet frame - see wtap_presence_flags in init.lua for bits.

frameinfoconst.captured_length

Mode: Retrieve only.

The captured packet length, and thus the length of the buffer in the FrameInfoConst.data field.

frameinfoconst.original_length

Mode: Retrieve only.

The on-the-wire packet length, which may be longer than the captured_length.

frameinfoconst.encap

Mode: Retrieve only.

The packet encapsulation type, if the file supports per-packet types.

See wtap_encaps in init.lua for possible packet encapsulation types to use as the value for this field.

frameinfoconst.comment

Mode: Retrieve only.

A comment for the packet; nil if there is none.

Global Functions

register_filehandler(filehandler)

將FileHandler注冊到Wireshark/tshark中，這樣他們就可以讀/寫這個新格式。
在調用此注冊函數之前，必須完成所有的函數和設置。
這個函數不能在讀/寫回調函數中調用。

Arguments

filehandler

The FileHandler object to be registered

Returns

the new type number for this file reader/write

deregister_filehandler(filehandler)

從Wireshark/tshark取消文件處理程序的注冊，使其不再用于讀取/寫入/顯示。這個函數不能在讀/寫回調函數中調用。

Arguments

filehandler

The FileHandler object to be deregistered