| Wireshark 4.7.0 The Wireshark network protocol analyzer

Loading...
Searching...
No Matches
Classes | Macros | Typedefs | Functions
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.