wtap_module.h File Reference

#include "wtap.h"
#include "wtap_opttypes.h"
#include <wsutil/file_util.h>

Go to the source code of this file.

Classes
struct	wtap
struct	wtap_dumper
	Wiretap dumper handle and associated state. More...

Macros
#define	PBSWAP64(p)
	Byte-swap an unaligned 64-bit quantity in place.
#define	PBSWAP32(p)
	Byte-swap an unaligned 32-bit quantity in place.
#define	PBSWAP16(p)
	Byte-swap an unaligned 16-bit quantity in place.

Typedefs
typedef bool(*	subtype_read_func) (struct wtap *wtap, wtap_rec *rec, int *err, char **err_info, int64_t *offset)
	Function pointer type for reading a record.
typedef bool(*	subtype_seek_read_func) (struct wtap *wtap, int64_t seek_off, wtap_rec *rec, int *err, char **err_info)
	Function pointer type for seeking and reading a record.
typedef void *	WFILE_T
	Abstract file handle for writing.
typedef bool(*	subtype_add_idb_func) (struct wtap_dumper *dumper, wtap_block_t idb, int *err, char **err_info)
	Function pointer type for adding an Interface Description Block (IDB).
typedef bool(*	subtype_write_func) (struct wtap_dumper *dumper, const wtap_rec *rec, int *err, char **err_info)
	Function pointer type for writing a record.
typedef bool(*	subtype_finish_func) (struct wtap_dumper *dumper, int *err, char **err_info)
	Function pointer type for finalizing a dump file.

Functions
WS_DLL_PUBLIC int	wtap_fstat (wtap *wth, ws_statb64 *statb, int *err)
	Retrieve file statistics for a wiretap handle.
WS_DLL_PUBLIC bool	wtap_dump_file_write (wtap_dumper *wdh, const void *buf, size_t bufsize, int *err)
	Write raw data to the dump file.
WS_DLL_PUBLIC int64_t	wtap_dump_file_seek (wtap_dumper *wdh, int64_t offset, int whence, int *err)
	Seek to a position in the dump file.
WS_DLL_PUBLIC int64_t	wtap_dump_file_tell (wtap_dumper *wdh, int *err)
	Get current position in the dump file.
WS_DLL_PUBLIC bool	wtap_read_bytes_or_eof (FILE_T fh, void *buf, unsigned int count, int *err, char **err_info)
	Read a specified number of bytes from a file or discard them.
WS_DLL_PUBLIC bool	wtap_read_bytes_or_eof_buffer (FILE_T fh, Buffer *buf, unsigned int count, int *err, char **err_info)
	Read a specified number of bytes into a Buffer, growing it as needed.
WS_DLL_PUBLIC bool	wtap_read_bytes (FILE_T fh, void *buf, unsigned int count, int *err, char **err_info)
	Read a specified number of bytes from a file or discard them.
WS_DLL_PUBLIC bool	wtap_read_bytes_buffer (FILE_T fh, Buffer *buf, unsigned length, int *err, char **err_info)
	Read a specified number of bytes into a Buffer, growing it as needed.
bool	wtap_full_file_read (wtap *wth, wtap_rec *rec, int *err, char **err_info, int64_t *data_offset)
	Read entire file contents as a single packet (sequential mode).
bool	wtap_full_file_seek_read (wtap *wth, int64_t seek_off, wtap_rec *rec, int *err, char **err_info)
	Read entire file contents as a single packet (seek mode).
void	wtap_add_idb (wtap *wth, wtap_block_t idb)
	Add an Interface Description Block (IDB) to a wiretap handle.
void	wtap_add_dpib (wtap *wth, wtap_block_t dpib)
	Add a DPIB to the dpibs list for a file.
void	wtapng_process_nrb (wtap *wth, wtap_block_t nrb)
	Invoke the registered callback with a Name Resolution Block (NRB).
void	wtapng_process_dsb (wtap *wth, wtap_block_t dsb)
	Invoke the registered callback with a Decryption Secrets Block (DSB).
void	wtap_register_compatibility_file_subtype_name (const char *old_name, const char *new_name)
	Register a compatibility alias for a file subtype name.
void	wtap_register_backwards_compatibility_lua_name (const char *name, int ft)
	Register a backwards compatibility Lua name for a file type.
WS_DLL_PUBLIC void	wtap_add_generated_idb (wtap *wth)
	Generate an IDB, given a wiretap handle for the file, using the file's encapsulation type, snapshot length, and time stamp resolution, and add it to the interface data for a file.
wtap_block_t	wtap_rec_generate_idb (const wtap_rec *rec)
	Generate an IDB, given a packet record, using the records's encapsulation type and time stamp resolution, and the default snap length for the encapsulation type. For use when a file has per-packet encapsulation, and the source is not passing along IDBs.

Detailed Description

Wiretap Library Copyright (c) 1998 by Gilbert Ramirez gram@.nosp@m.alum.nosp@m.ni.ri.nosp@m.ce.e.nosp@m.du

SPDX-License-Identifier: GPL-2.0-or-later

Macro Definition Documentation

PBSWAP16

#define PBSWAP16

(

p

)

Value:

    {            \
        uint8_t tmp;        \
        tmp = (p)[1];      \
        (p)[1] = (p)[0];   \
        (p)[0] = tmp;      \
    }

Byte-swap an unaligned 16-bit quantity in place.

Parameters

p	Pointer to 2-byte array to swap.

PBSWAP32

#define PBSWAP32

(

p

)

Value:

    {            \
        uint8_t tmp;         \
        tmp = (p)[3];       \
        (p)[3] = (p)[0];    \
        (p)[0] = tmp;       \
        tmp = (p)[2];       \
        (p)[2] = (p)[1];    \
        (p)[1] = tmp;       \
    }

Byte-swap an unaligned 32-bit quantity in place.

Parameters

p	Pointer to 4-byte array to swap.

PBSWAP64

#define PBSWAP64

(

p

)

Value:

    {            \
        uint8_t tmp;        \
        tmp = (p)[7];      \
        (p)[7] = (p)[0];   \
        (p)[0] = tmp;      \
        tmp = (p)[6];      \
        (p)[6] = (p)[1];   \
        (p)[1] = tmp;      \
        tmp = (p)[5];      \
        (p)[5] = (p)[2];   \
        (p)[2] = tmp;      \
        tmp = (p)[4];      \
        (p)[4] = (p)[3];   \
        (p)[3] = tmp;      \
    }

Byte-swap an unaligned 64-bit quantity in place.

Parameters

p	Pointer to 8-byte array to swap.

Typedef Documentation

subtype_add_idb_func

typedef bool(* subtype_add_idb_func) (struct wtap_dumper *dumper, wtap_block_t idb, int *err, char **err_info)

Function pointer type for adding an Interface Description Block (IDB).

Parameters

dumper	Wiretap dumper handle.
idb	Interface Description Block to add.
err	Optional error code output.
err_info	Optional error info string.

Returns

true on success, false on failure.

subtype_finish_func

typedef bool(* subtype_finish_func) (struct wtap_dumper *dumper, int *err, char **err_info)

Function pointer type for finalizing a dump file.

Parameters

dumper	Wiretap dumper handle.
err	Optional error code output.
err_info	Optional error info string.

Returns

true on success, false on failure.

subtype_read_func

typedef bool(* subtype_read_func) (struct wtap *wtap, wtap_rec *rec, int *err, char **err_info, int64_t *offset)

Function pointer type for reading a record.

Parameters

wtap	Wiretap handle.
rec	Output record.
err	Optional error code output.
err_info	Optional error info string.
offset	Optional offset output.

Returns

true on success, false on failure.

subtype_seek_read_func

typedef bool(* subtype_seek_read_func) (struct wtap *wtap, int64_t seek_off, wtap_rec *rec, int *err, char **err_info)

Function pointer type for seeking and reading a record.

Parameters

wtap	Wiretap handle.
seek_off	Offset to seek to.
rec	Output record.
err	Optional error code output.
err_info	Optional error info string.

Returns

true on success, false on failure.

subtype_write_func

typedef bool(* subtype_write_func) (struct wtap_dumper *dumper, const wtap_rec *rec, int *err, char **err_info)

Function pointer type for writing a record.

Parameters

dumper	Wiretap dumper handle.
rec	Record to write.
err	Optional error code output.
err_info	Optional error info string.

Returns

true on success, false on failure.

WFILE_T

typedef void* WFILE_T

Abstract file handle for writing.

May represent a FILE* or a handle for writing a compressed file.

Function Documentation

wtap_add_dpib()

void wtap_add_dpib	(	wtap *	wth,
		wtap_block_t	dpib
	)

Add a DPIB to the dpibs list for a file.

Used during parsing to register a Decryption Parameters Info Block (DPIB).

Parameters

wth	Wiretap handle.
dpib	DPIB block to add.

wtap_add_generated_idb()

WS_DLL_PUBLIC void wtap_add_generated_idb

(

wtap *

wth

)

Generate an IDB, given a wiretap handle for the file, using the file's encapsulation type, snapshot length, and time stamp resolution, and add it to the interface data for a file.

Note

This requires that the encapsulation type and time stamp resolution not be per-packet; it will terminate the process if either of them are.

Parameters

wth	The wiretap handle for the file.

wtap_add_idb()

void wtap_add_idb	(	wtap *	wth,
		wtap_block_t	idb
	)

Add an Interface Description Block (IDB) to a wiretap handle.

Used during file parsing to register interface metadata.

Parameters

wth	Wiretap handle.
idb	IDB block to add.

wtap_dump_file_seek()

WS_DLL_PUBLIC int64_t wtap_dump_file_seek	(	wtap_dumper *	wdh,
		int64_t	offset,
		int	whence,
		int *	err
	)

Seek to a position in the dump file.

Parameters

wdh	Wiretap dumper handle.
offset	Byte offset to seek to.
whence	Seek origin (e.g., SEEK_SET).
err	Optional error code output.

Returns

New file position on success, -1 on failure.

Note

If a module uses this function, it should set writing_must_seek to true in its file_type_subtype_info. Seeking is not supported when writing compressed files.

wtap_dump_file_tell()

WS_DLL_PUBLIC int64_t wtap_dump_file_tell	(	wtap_dumper *	wdh,
		int *	err
	)

Get current position in the dump file.

Parameters

wdh	Wiretap dumper handle.
err	Optional error code output.

Returns

Current file position on success, -1 on failure.

Note

If a module uses this function, it should set writing_must_seek to true in its file_type_subtype_info. If a module never seeks but needs to know the number of bytes written, use the bytes_dumped member of wtap_dumper in order to preserve support for compression.

wtap_dump_file_write()

WS_DLL_PUBLIC bool wtap_dump_file_write	(	wtap_dumper *	wdh,
		const void *	buf,
		size_t	bufsize,
		int *	err
	)

Write raw data to the dump file.

Parameters

wdh	Wiretap dumper handle.
buf	Pointer to data buffer.
bufsize	Size of buffer in bytes.
err	Optional error code output.

Returns

true on success, false on failure.

wtap_fstat()

WS_DLL_PUBLIC int wtap_fstat	(	wtap *	wth,
		ws_statb64 *	statb,
		int *	err
	)

Retrieve file statistics for a wiretap handle.

Parameters

wth	Wiretap handle.
statb	Pointer to stat structure to populate.
err	Optional error code output.

Returns

0 on success, -1 on failure.

wtap_full_file_read()

bool wtap_full_file_read	(	wtap *	wth,
		wtap_rec *	rec,
		int *	err,
		char **	err_info,
		int64_t *	data_offset
	)

Read entire file contents as a single packet (sequential mode).

Used for formats that treat the whole file as one record.

Parameters

wth	Wiretap handle.
rec	Output record.
err	Output error code.
err_info	Optional error info string.
data_offset	Output offset of packet data.

Returns

true on success; false on error.

wtap_full_file_seek_read()

bool wtap_full_file_seek_read	(	wtap *	wth,
		int64_t	seek_off,
		wtap_rec *	rec,
		int *	err,
		char **	err_info
	)

Read entire file contents as a single packet (seek mode).

Used for formats that support random access to a single-record file.

Parameters

wth	Wiretap handle.
seek_off	Offset to seek to.
rec	Output record.
err	Output error code.
err_info	Optional error info string.

Returns

true on success; false on error.

wtap_read_bytes()

WS_DLL_PUBLIC bool wtap_read_bytes	(	FILE_T	fh,
		void *	buf,
		unsigned int	count,
		int *	err,
		char **	err_info
	)

Read a specified number of bytes from a file or discard them.

• If buf is NULL, bytes are discarded.
• On short read or EOF: returns false, *err = WTAP_ERR_SHORT_READ.
• On read error: returns false, *err and *err_info set appropriately.

Parameters

fh	File handle to read from.
buf	Destination buffer, or NULL to discard bytes.
count	Number of bytes to read.
err	Output error code (WTAP_ERR_SHORT_READ on short read or EOF).
err_info	Optional error info string on failure.

Returns

true on success; false on short read or error.

wtap_read_bytes_buffer()

WS_DLL_PUBLIC bool wtap_read_bytes_buffer	(	FILE_T	fh,
		Buffer *	buf,
		unsigned	length,
		int *	err,
		char **	err_info
	)

Read a specified number of bytes into a Buffer, growing it as needed.

• If buf is NULL, bytes are discarded.
• On short read or EOF: returns false, *err = WTAP_ERR_SHORT_READ.
• On read error: returns false, *err and *err_info set appropriately.

Parameters

fh	File handle to read from.
buf	Buffer to receive data.
length	Number of bytes to read.
err	Output error code (WTAP_ERR_SHORT_READ on short read or EOF).
err_info	Optional error info string on failure.

Returns

true on success; false on short read or error.

wtap_read_bytes_or_eof()

WS_DLL_PUBLIC bool wtap_read_bytes_or_eof	(	FILE_T	fh,
		void *	buf,
		unsigned int	count,
		int *	err,
		char **	err_info
	)

Read a specified number of bytes from a file or discard them.

• If buf is NULL, bytes are discarded.
• On EOF: returns false, *err = 0.
• On short read: returns false, *err = WTAP_ERR_SHORT_READ.
• On error: returns false, *err and *err_info set appropriately.

Parameters

fh	File handle to read from.
buf	Destination buffer, or NULL to discard bytes.
count	Number of bytes to read.
err	Output error code (0 for EOF, WTAP_ERR_SHORT_READ for short read, or other on failure).
err_info	Optional error info string on failure.

Returns

true on success; false on EOF, short read, or error.

wtap_read_bytes_or_eof_buffer()

WS_DLL_PUBLIC bool wtap_read_bytes_or_eof_buffer	(	FILE_T	fh,
		Buffer *	buf,
		unsigned int	count,
		int *	err,
		char **	err_info
	)

Read a specified number of bytes into a Buffer, growing it as needed.

• On EOF: returns false, *err = 0.
• On short read: returns false, *err = WTAP_ERR_SHORT_READ.
• On error: returns false, *err and *err_info set appropriately.

Parameters

fh	File handle to read from.
buf	Destination buffer, or NULL to discard bytes.
count	Number of bytes to read.
err	Output error code (0 for EOF, WTAP_ERR_SHORT_READ for short read, or other on failure).
err_info	Optional error info string on failure.

Returns

true on success; false on EOF, short read, or error.

wtap_rec_generate_idb()

wtap_block_t wtap_rec_generate_idb

(

const wtap_rec *

rec

)

Generate an IDB, given a packet record, using the records's encapsulation type and time stamp resolution, and the default snap length for the encapsulation type. For use when a file has per-packet encapsulation, and the source is not passing along IDBs.

Note

This requires that the record type be REC_TYPE_PACKET, and the encapsulation type and time stamp resolution not be per-packet; it will terminate the process if any of them are.

Parameters

rec	The packet record.

Returns

A newly allocated IDB block.

< packet

< time stamp

wtap_register_backwards_compatibility_lua_name()

void wtap_register_backwards_compatibility_lua_name	(	const char *	name,
		int	ft
	)

Register a backwards compatibility Lua name for a file type.

Associates a legacy Lua-accessible name with a file type identifier.

Parameters

name	Legacy Lua name.
ft	File type identifier.

wtap_register_compatibility_file_subtype_name()

void wtap_register_compatibility_file_subtype_name	(	const char *	old_name,
		const char *	new_name
	)

Register a compatibility alias for a file subtype name.

Used to map legacy subtype names to updated identifiers.

Parameters

old_name	Deprecated subtype name.
new_name	Canonical subtype name.

wtapng_process_dsb()

void wtapng_process_dsb	(	wtap *	wth,
		wtap_block_t	dsb
	)

Invoke the registered callback with a Decryption Secrets Block (DSB).

Used to process DSBs during capture file parsing.

Parameters

wth	Wiretap handle.
dsb	DSB block to process.

wtapng_process_nrb()

void wtapng_process_nrb	(	wtap *	wth,
		wtap_block_t	nrb
	)

Invoke the registered callback with a Name Resolution Block (NRB).

Used to process NRBs during capture file parsing.

Parameters

wth	Wiretap handle.
nrb	NRB block to process.