| 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 (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.

## ◆ 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.

## ◆ 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.

This returns an error on a short read, even if the short read hit the EOF immediately. (The assumption is that each packet has a header followed by raw packet data, and that we've already read the header, so if we get an EOF trying to read the packet data, the file has been cut short, even if the read didn't read any data at all.)

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_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.

## ◆ 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.