/** @file
 *
 * Wiretap Library
 * Copyright (c) 1998 by Gilbert Ramirez <gram@alumni.rice.edu>
 *
 * SPDX-License-Identifier: GPL-2.0-or-later
 */

#ifndef __WTAP_H__
#define __WTAP_H__

#include <wireshark.h>
#include <time.h>
#include <wsutil/array.h>
#include <wsutil/buffer.h>
#include <wsutil/nstime.h>
#include <wsutil/inet_addr.h>
#include <wsutil/file_compressed.h>
#include "wtap_opttypes.h"

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/* Encapsulation types. Choose names that truly reflect
 * what is contained in the packet trace file.
 *
 * WTAP_ENCAP_PER_PACKET is a value passed to "wtap_dump_open()" or
 * "wtap_dump_fdopen()" to indicate that there is no single encapsulation
 * type for all packets in the file; this may cause those routines to
 * fail if the capture file format being written can't support that.
 * It's also returned by "wtap_file_encap()" for capture files that
 * don't have a single encapsulation type for all packets in the file.
 *
 * WTAP_ENCAP_UNKNOWN is returned by "wtap_pcap_encap_to_wtap_encap()"
 * if it's handed an unknown encapsulation. It is also used by file
 * types for encapsulations which are unsupported by libwiretap.
 *
 * WTAP_ENCAP_NONE is an initial value used by file types like pcapng
 * that do not have a single file level encapsulation type. If and when
 * something that indicate encapsulation is read, the encapsulation will
 * change (possibly to WTAP_ENCAP_PER_PACKET) and appropriate IDBs will
 * be generated. If a file type uses this value, it MUST provide IDBs
 * (possibly fake) when the encapsulation changes; otherwise, it should
 * return WTAP_ENCAP_UNKNOWN so that attempts to write an output file
 * without reading the entire input file first fail gracefully.
 *
 * WTAP_ENCAP_FDDI_BITSWAPPED is for FDDI captures on systems where the
 * MAC addresses you get from the hardware are bit-swapped.  Ideally,
 * the driver would tell us that, but I know of none that do, so, for
 * now, we base it on the machine on which we're *reading* the
 * capture, rather than on the machine on which the capture was taken
 * (they're probably likely to be the same).  We assume that they're
 * bit-swapped on everything except for systems running Ultrix, Alpha
 * systems, and BSD/OS systems (that's what "tcpdump" does; I guess
 * Digital decided to bit-swap addresses in the hardware or in the
 * driver, and I guess BSDI bit-swapped them in the driver, given that
 * BSD/OS generally runs on Boring Old PC's).  If we create a wiretap
 * save file format, we'd use the WTAP_ENCAP values to flag the
 * encapsulation of a packet, so there we'd at least be able to base
 * it on the machine on which the capture was taken.
 *
 * WTAP_ENCAP_LINUX_ATM_CLIP is the encapsulation you get with the
 * ATM on Linux code from <http://linux-atm.sourceforge.net/>;
 * that code adds a DLT_ATM_CLIP DLT_ code of 19, and that
 * encapsulation isn't the same as the DLT_ATM_RFC1483 encapsulation
 * presumably used on some BSD systems, which we turn into
 * WTAP_ENCAP_ATM_RFC1483.
 *
 * WTAP_ENCAP_NULL corresponds to DLT_NULL from "libpcap".  This
 * corresponds to
 *
 *  1) PPP-over-HDLC encapsulation, at least with some versions
 *     of ISDN4BSD (but not the current ones, it appears, unless
 *     I've missed something);
 *
 *  2) a 4-byte header containing the AF_ address family, in
 *     the byte order of the machine that saved the capture,
 *     for the packet, as used on many BSD systems for the
 *     loopback device and some other devices, or a 4-byte header
 *     containing the AF_ address family in network byte order,
 *     as used on recent OpenBSD systems for the loopback device;
 *
 *  3) a 4-byte header containing 2 octets of 0 and an Ethernet
 *     type in the byte order from an Ethernet header, that being
 *     what older versions of "libpcap" on Linux turn the Ethernet
 *     header for loopback interfaces into (0.6.0 and later versions
 *     leave the Ethernet header alone and make it DLT_EN10MB). */
#define WTAP_ENCAP_NONE                         -2
#define WTAP_ENCAP_PER_PACKET                   -1
#define WTAP_ENCAP_UNKNOWN                        0
#define WTAP_ENCAP_ETHERNET                       1
#define WTAP_ENCAP_TOKEN_RING                     2
#define WTAP_ENCAP_SLIP                           3
#define WTAP_ENCAP_PPP                            4
#define WTAP_ENCAP_FDDI                           5
#define WTAP_ENCAP_FDDI_BITSWAPPED                6
#define WTAP_ENCAP_RAW_IP                         7
#define WTAP_ENCAP_ARCNET                         8
#define WTAP_ENCAP_ARCNET_LINUX                   9
#define WTAP_ENCAP_ATM_RFC1483                   10
#define WTAP_ENCAP_LINUX_ATM_CLIP                11
#define WTAP_ENCAP_LAPB                          12
#define WTAP_ENCAP_ATM_PDUS                      13
#define WTAP_ENCAP_ATM_PDUS_UNTRUNCATED          14
#define WTAP_ENCAP_NULL                          15
#define WTAP_ENCAP_ASCEND                        16
#define WTAP_ENCAP_ISDN                          17
#define WTAP_ENCAP_IP_OVER_FC                    18
#define WTAP_ENCAP_PPP_WITH_PHDR                 19
#define WTAP_ENCAP_IEEE_802_11                   20
#define WTAP_ENCAP_IEEE_802_11_PRISM             21
#define WTAP_ENCAP_IEEE_802_11_WITH_RADIO        22
#define WTAP_ENCAP_IEEE_802_11_RADIOTAP          23
#define WTAP_ENCAP_IEEE_802_11_AVS               24
#define WTAP_ENCAP_SLL                           25
#define WTAP_ENCAP_FRELAY                        26
#define WTAP_ENCAP_FRELAY_WITH_PHDR              27
#define WTAP_ENCAP_CHDLC                         28
#define WTAP_ENCAP_CISCO_IOS                     29
#define WTAP_ENCAP_LOCALTALK                     30
#define WTAP_ENCAP_OLD_PFLOG                     31
#define WTAP_ENCAP_HHDLC                         32
#define WTAP_ENCAP_DOCSIS                        33
#define WTAP_ENCAP_COSINE                        34
#define WTAP_ENCAP_WFLEET_HDLC                   35
#define WTAP_ENCAP_SDLC                          36
#define WTAP_ENCAP_TZSP                          37
#define WTAP_ENCAP_ENC                           38
#define WTAP_ENCAP_PFLOG                         39
#define WTAP_ENCAP_CHDLC_WITH_PHDR               40
#define WTAP_ENCAP_BLUETOOTH_H4                  41
#define WTAP_ENCAP_MTP2                          42
#define WTAP_ENCAP_MTP3                          43
#define WTAP_ENCAP_IRDA                          44
#define WTAP_ENCAP_USER0                         45
#define WTAP_ENCAP_USER1                         46
#define WTAP_ENCAP_USER2                         47
#define WTAP_ENCAP_USER3                         48
#define WTAP_ENCAP_USER4                         49
#define WTAP_ENCAP_USER5                         50
#define WTAP_ENCAP_USER6                         51
#define WTAP_ENCAP_USER7                         52
#define WTAP_ENCAP_USER8                         53
#define WTAP_ENCAP_USER9                         54
#define WTAP_ENCAP_USER10                        55
#define WTAP_ENCAP_USER11                        56
#define WTAP_ENCAP_USER12                        57
#define WTAP_ENCAP_USER13                        58
#define WTAP_ENCAP_USER14                        59
#define WTAP_ENCAP_USER15                        60
#define WTAP_ENCAP_SYMANTEC                      61
#define WTAP_ENCAP_APPLE_IP_OVER_IEEE1394        62
#define WTAP_ENCAP_BACNET_MS_TP                  63
#define WTAP_ENCAP_NETTL_RAW_ICMP                64
#define WTAP_ENCAP_NETTL_RAW_ICMPV6              65
#define WTAP_ENCAP_GPRS_LLC                      66
#define WTAP_ENCAP_JUNIPER_ATM1                  67
#define WTAP_ENCAP_JUNIPER_ATM2                  68
#define WTAP_ENCAP_REDBACK                       69
#define WTAP_ENCAP_NETTL_RAW_IP                  70
#define WTAP_ENCAP_NETTL_ETHERNET                71
#define WTAP_ENCAP_NETTL_TOKEN_RING              72
#define WTAP_ENCAP_NETTL_FDDI                    73
#define WTAP_ENCAP_NETTL_UNKNOWN                 74
#define WTAP_ENCAP_MTP2_WITH_PHDR                75
#define WTAP_ENCAP_JUNIPER_PPPOE                 76
#define WTAP_ENCAP_GCOM_TIE1                     77
#define WTAP_ENCAP_GCOM_SERIAL                   78
#define WTAP_ENCAP_NETTL_X25                     79
#define WTAP_ENCAP_K12                           80
#define WTAP_ENCAP_JUNIPER_MLPPP                 81
#define WTAP_ENCAP_JUNIPER_MLFR                  82
#define WTAP_ENCAP_JUNIPER_ETHER                 83
#define WTAP_ENCAP_JUNIPER_PPP                   84
#define WTAP_ENCAP_JUNIPER_FRELAY                85
#define WTAP_ENCAP_JUNIPER_CHDLC                 86
#define WTAP_ENCAP_JUNIPER_GGSN                  87
#define WTAP_ENCAP_LINUX_LAPD                    88
#define WTAP_ENCAP_CATAPULT_DCT2000              89
#define WTAP_ENCAP_BER                           90
#define WTAP_ENCAP_JUNIPER_VP                    91
#define WTAP_ENCAP_USB_FREEBSD                   92
#define WTAP_ENCAP_IEEE802_16_MAC_CPS            93
#define WTAP_ENCAP_NETTL_RAW_TELNET              94
#define WTAP_ENCAP_USB_LINUX                     95
#define WTAP_ENCAP_MPEG                          96
#define WTAP_ENCAP_PPI                           97
#define WTAP_ENCAP_ERF                           98
#define WTAP_ENCAP_BLUETOOTH_H4_WITH_PHDR        99
#define WTAP_ENCAP_SITA                         100
#define WTAP_ENCAP_SCCP                         101
#define WTAP_ENCAP_BLUETOOTH_HCI                102 /*raw packets without a transport layer header e.g. H4*/
#define WTAP_ENCAP_IPMB_KONTRON                 103
#define WTAP_ENCAP_IEEE802_15_4                 104
#define WTAP_ENCAP_X2E_XORAYA                   105
#define WTAP_ENCAP_FLEXRAY                      106
#define WTAP_ENCAP_LIN                          107
#define WTAP_ENCAP_MOST                         108
#define WTAP_ENCAP_CAN20B                       109
#define WTAP_ENCAP_LAYER1_EVENT                 110
#define WTAP_ENCAP_X2E_SERIAL                   111
#define WTAP_ENCAP_I2C_LINUX                    112
#define WTAP_ENCAP_IEEE802_15_4_NONASK_PHY      113
#define WTAP_ENCAP_TNEF                         114
#define WTAP_ENCAP_USB_LINUX_MMAPPED            115
#define WTAP_ENCAP_GSM_UM                       116
#define WTAP_ENCAP_DPNSS                        117
#define WTAP_ENCAP_PACKETLOGGER                 118
#define WTAP_ENCAP_NSTRACE_1_0                  119
#define WTAP_ENCAP_NSTRACE_2_0                  120
#define WTAP_ENCAP_FIBRE_CHANNEL_FC2            121
#define WTAP_ENCAP_FIBRE_CHANNEL_FC2_WITH_FRAME_DELIMS 122
#define WTAP_ENCAP_JPEG_JFIF                    123 /* obsoleted by WTAP_ENCAP_MIME*/
#define WTAP_ENCAP_IPNET                        124
#define WTAP_ENCAP_SOCKETCAN                    125
#define WTAP_ENCAP_IEEE_802_11_NETMON           126
#define WTAP_ENCAP_IEEE802_15_4_NOFCS           127
#define WTAP_ENCAP_RAW_IPFIX                    128
#define WTAP_ENCAP_RAW_IP4                      129
#define WTAP_ENCAP_RAW_IP6                      130
#define WTAP_ENCAP_LAPD                         131
#define WTAP_ENCAP_DVBCI                        132
#define WTAP_ENCAP_MUX27010                     133
#define WTAP_ENCAP_MIME                         134
#define WTAP_ENCAP_NETANALYZER                  135
#define WTAP_ENCAP_NETANALYZER_TRANSPARENT      136
#define WTAP_ENCAP_IP_OVER_IB_SNOOP             137
#define WTAP_ENCAP_MPEG_2_TS                    138
#define WTAP_ENCAP_PPP_ETHER                    139
#define WTAP_ENCAP_NFC_LLCP                     140
#define WTAP_ENCAP_NFLOG                        141
#define WTAP_ENCAP_V5_EF                        142
#define WTAP_ENCAP_BACNET_MS_TP_WITH_PHDR       143
#define WTAP_ENCAP_IXVERIWAVE                   144
#define WTAP_ENCAP_SDH                          145
#define WTAP_ENCAP_DBUS                         146
#define WTAP_ENCAP_AX25_KISS                    147
#define WTAP_ENCAP_AX25                         148
#define WTAP_ENCAP_SCTP                         149
#define WTAP_ENCAP_INFINIBAND                   150
#define WTAP_ENCAP_JUNIPER_SVCS                 151
#define WTAP_ENCAP_USBPCAP                      152
#define WTAP_ENCAP_RTAC_SERIAL                  153
#define WTAP_ENCAP_BLUETOOTH_LE_LL              154
#define WTAP_ENCAP_WIRESHARK_UPPER_PDU          155
#define WTAP_ENCAP_STANAG_4607                  156
#define WTAP_ENCAP_STANAG_5066_D_PDU            157
#define WTAP_ENCAP_NETLINK                      158
#define WTAP_ENCAP_BLUETOOTH_LINUX_MONITOR      159
#define WTAP_ENCAP_BLUETOOTH_BREDR_BB           160
#define WTAP_ENCAP_BLUETOOTH_LE_LL_WITH_PHDR    161
#define WTAP_ENCAP_NSTRACE_3_0                  162
#define WTAP_ENCAP_LOGCAT                       163
#define WTAP_ENCAP_LOGCAT_BRIEF                 164
#define WTAP_ENCAP_LOGCAT_PROCESS               165
#define WTAP_ENCAP_LOGCAT_TAG                   166
#define WTAP_ENCAP_LOGCAT_THREAD                167
#define WTAP_ENCAP_LOGCAT_TIME                  168
#define WTAP_ENCAP_LOGCAT_THREADTIME            169
#define WTAP_ENCAP_LOGCAT_LONG                  170
#define WTAP_ENCAP_PKTAP                        171
#define WTAP_ENCAP_EPON                         172
#define WTAP_ENCAP_IPMI_TRACE                   173
#define WTAP_ENCAP_LOOP                         174
#define WTAP_ENCAP_JSON                         175
#define WTAP_ENCAP_NSTRACE_3_5                  176
#define WTAP_ENCAP_ISO14443                     177
#define WTAP_ENCAP_GFP_T                        178
#define WTAP_ENCAP_GFP_F                        179
#define WTAP_ENCAP_IP_OVER_IB_PCAP              180
#define WTAP_ENCAP_JUNIPER_VN                   181
#define WTAP_ENCAP_USB_DARWIN                   182
#define WTAP_ENCAP_LORATAP                      183
#define WTAP_ENCAP_3MB_ETHERNET                 184
#define WTAP_ENCAP_VSOCK                        185
#define WTAP_ENCAP_NORDIC_BLE                   186
#define WTAP_ENCAP_NETMON_NET_NETEVENT          187
#define WTAP_ENCAP_NETMON_HEADER                188
#define WTAP_ENCAP_NETMON_NET_FILTER            189
#define WTAP_ENCAP_NETMON_NETWORK_INFO_EX       190
#define WTAP_ENCAP_MA_WFP_CAPTURE_V4            191
#define WTAP_ENCAP_MA_WFP_CAPTURE_V6            192
#define WTAP_ENCAP_MA_WFP_CAPTURE_2V4           193
#define WTAP_ENCAP_MA_WFP_CAPTURE_2V6           194
#define WTAP_ENCAP_MA_WFP_CAPTURE_AUTH_V4       195
#define WTAP_ENCAP_MA_WFP_CAPTURE_AUTH_V6       196
#define WTAP_ENCAP_JUNIPER_ST                   197
#define WTAP_ENCAP_ETHERNET_MPACKET             198
#define WTAP_ENCAP_DOCSIS31_XRA31               199
#define WTAP_ENCAP_DPAUXMON                     200
#define WTAP_ENCAP_RUBY_MARSHAL                 201
#define WTAP_ENCAP_RFC7468                      202
#define WTAP_ENCAP_SYSTEMD_JOURNAL              203 /* Event, not a packet */
#define WTAP_ENCAP_EBHSCR                       204
#define WTAP_ENCAP_VPP                          205
#define WTAP_ENCAP_IEEE802_15_4_TAP             206
#define WTAP_ENCAP_LOG_3GPP                     207
#define WTAP_ENCAP_USB_2_0                      208
#define WTAP_ENCAP_MP4                          209
#define WTAP_ENCAP_SLL2                         210
#define WTAP_ENCAP_ZWAVE_SERIAL                 211
#define WTAP_ENCAP_ETW                          212
#define WTAP_ENCAP_ERI_ENB_LOG                  213
#define WTAP_ENCAP_ZBNCP                        214
#define WTAP_ENCAP_USB_2_0_LOW_SPEED            215
#define WTAP_ENCAP_USB_2_0_FULL_SPEED           216
#define WTAP_ENCAP_USB_2_0_HIGH_SPEED           217
#define WTAP_ENCAP_AUTOSAR_DLT                  218
#define WTAP_ENCAP_AUERSWALD_LOG                219
#define WTAP_ENCAP_ATSC_ALP                     220
#define WTAP_ENCAP_FIRA_UCI                     221
#define WTAP_ENCAP_SILABS_DEBUG_CHANNEL         222
#define WTAP_ENCAP_MDB                          223
#define WTAP_ENCAP_EMS                          224
#define WTAP_ENCAP_DECT_NR                      225
#define WTAP_ENCAP_MMODULE                      226
#define WTAP_ENCAP_PROCMON                      227
#define WTAP_ENCAP_ZWAVE_TAP                    228

/* After adding new item here, please also add new item to encap_table_base array */

#define WTAP_NUM_ENCAP_TYPES                    wtap_get_num_encap_types()

/* Value to be used as a file type/subtype value if the type is unknown */
#define WTAP_FILE_TYPE_SUBTYPE_UNKNOWN                        -1

/* timestamp precision (currently only these values are supported) */
#define WTAP_TSPREC_UNKNOWN    -2 /**< Timestamp precision is unknown. */
#define WTAP_TSPREC_PER_PACKET -1 /**< As a per-file value, means each packet carries its own precision. */

/*
 * These values are the number of digits of precision after the integral part.
 * They're the same as WS_TSPREC values; we define them here so that
 * tools/make-enums.py sees them.
 */
#define WTAP_TSPREC_SEC       0 /**< Precision: 1 second (0 fractional digits). */
#define WTAP_TSPREC_100_MSEC  1 /**< Precision: 100 milliseconds (1 fractional digit). */
#define WTAP_TSPREC_DSEC      1 /**< Precision: decisecond — alias for #WTAP_TSPREC_100_MSEC (backwards compatibility). */
#define WTAP_TSPREC_10_MSEC   2 /**< Precision: 10 milliseconds (2 fractional digits). */
#define WTAP_TSPREC_CSEC      2 /**< Precision: centisecond — alias for #WTAP_TSPREC_10_MSEC (backwards compatibility). */
#define WTAP_TSPREC_MSEC      3 /**< Precision: 1 millisecond (3 fractional digits). */
#define WTAP_TSPREC_100_USEC  4 /**< Precision: 100 microseconds (4 fractional digits). */
#define WTAP_TSPREC_10_USEC   5 /**< Precision: 10 microseconds (5 fractional digits). */
#define WTAP_TSPREC_USEC      6 /**< Precision: 1 microsecond (6 fractional digits). */
#define WTAP_TSPREC_100_NSEC  7 /**< Precision: 100 nanoseconds (7 fractional digits). */
#define WTAP_TSPREC_10_NSEC   8 /**< Precision: 10 nanoseconds (8 fractional digits). */
#define WTAP_TSPREC_NSEC      9 /**< Precision: 1 nanosecond (9 fractional digits). */
/* if you add to the above, update wtap_tsprec_string() */

/*
 * Maximum packet sizes.
 *
 * For most link-layer types, we use 262144, which is currently
 * libpcap's MAXIMUM_SNAPLEN.
 *
 * For WTAP_ENCAP_DBUS, the maximum is 128MiB, as per
 *
 *    https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-messages
 *
 * For WTAP_ENCAP_EBHSCR, the maximum is 8MiB, as per
 *
 *    https://www.elektrobit.com/ebhscr
 *
 * For WTAP_ENCAP_USBPCAP, the maximum is 128MiB, as per
 *
 *    https://gitlab.com/wireshark/wireshark/-/issues/15985
 *
 * We don't want to write out files that specify a maximum packet size
 * greater than 262144 if we don't have to, as software reading those
 * files might allocate a buffer much larger than necessary, wasting memory.
 */
#define WTAP_MAX_PACKET_SIZE_STANDARD    262144U
#define WTAP_MAX_PACKET_SIZE_USBPCAP     (128U*1024U*1024U)
#define WTAP_MAX_PACKET_SIZE_EBHSCR      (32U*1024U*1024U)
#define WTAP_MAX_PACKET_SIZE_DBUS        (128U*1024U*1024U)

/*
 * "Pseudo-headers" are used to supply to the clients of wiretap
 * per-packet information that's not part of the packet payload
 * proper.
 *
 * NOTE: do not use pseudo-header structures to hold information
 * used by the code to read a particular capture file type; to
 * keep that sort of state information, define a private structure
 * to hold that information in your code, and allocate one of those
 * structures and set the "priv" member of the wth structure to
 * point to the allocated structure in the "open" routine for that
 * capture file type if the open succeeds.  See various other capture
 * file type handlers for examples of that.
 */


/**
 * @brief Pseudo-header for Ethernet capture files carrying FCS length metadata.
 */
struct eth_phdr {
    int fcs_len; /**< Number of bytes of FCS appended to the frame; -1 if unknown. */
};

#define FROM_DCE 0x80 /**< Flag bit indicating the packet was transmitted from the DCE toward the DTE. */

/**
 * @brief Pseudo-header for DTE/DCE capture files (LAPB, V.120, Frame Relay) carrying direction metadata.
 */
struct dte_dce_phdr {
    uint8_t flags; /**< Direction flags; FROM_DCE set means the packet originated from the DCE; clear means from the DTE. */
};

/**
 * @brief Pseudo-header for ISDN capture files carrying direction and channel metadata.
 */
struct isdn_phdr {
    bool    uton;    /**< Direction of the packet: true = user-to-network (UNI), false = network-to-user. */
    uint8_t channel; /**< Logical channel number: 0 = D-channel (signalling), n = B-channel n (bearer). */
};

/* Packet "pseudo-header" for ATM capture files.
   Not all of this information is supplied by all capture types.
   These originally came from the Network General (DOS-based)
   ATM Sniffer file format, but we've added some additional
   items. */

/*
 * Status bits.
 */
#define ATM_RAW_CELL         0x01 /* true if the packet is a single cell */
#define ATM_NO_HEC           0x02 /* true if the cell has HEC stripped out */
#define ATM_AAL2_NOPHDR      0x04 /* true if the AAL2 PDU has no pseudo-header */
#define ATM_REASSEMBLY_ERROR 0x08 /* true if this is an incompletely-reassembled PDU */

/*
 * AAL types.
 */
#define AAL_UNKNOWN     0  /* AAL unknown */
#define AAL_1           1  /* AAL1 */
#define AAL_2           2  /* AAL2 */
#define AAL_3_4         3  /* AAL3/4 */
#define AAL_5           4  /* AAL5 */
#define AAL_USER        5  /* User AAL */
#define AAL_SIGNALLING  6  /* Signaling AAL */
#define AAL_OAMCELL     7  /* OAM cell */

/*
 * Traffic types.
 */
#define TRAF_UNKNOWN    0  /* Unknown */
#define TRAF_LLCMX      1  /* LLC multiplexed (RFC 1483) */
#define TRAF_VCMX       2  /* VC multiplexed (RFC 1483) */
#define TRAF_LANE       3  /* LAN Emulation */
#define TRAF_ILMI       4  /* ILMI */
#define TRAF_FR         5  /* Frame Relay */
#define TRAF_SPANS      6  /* FORE SPANS */
#define TRAF_IPSILON    7  /* Ipsilon */
#define TRAF_UMTS_FP    8  /* UMTS Frame Protocol */
#define TRAF_GPRS_NS    9  /* GPRS Network Services */
#define TRAF_SSCOP     10  /* SSCOP */

/*
 * Traffic subtypes.
 */
#define TRAF_ST_UNKNOWN     0   /* Unknown */

/*
 * For TRAF_VCMX:
 */
#define TRAF_ST_VCMX_802_3_FCS   1  /* 802.3 with an FCS */
#define TRAF_ST_VCMX_802_4_FCS   2  /* 802.4 with an FCS */
#define TRAF_ST_VCMX_802_5_FCS   3  /* 802.5 with an FCS */
#define TRAF_ST_VCMX_FDDI_FCS    4  /* FDDI with an FCS */
#define TRAF_ST_VCMX_802_6_FCS   5  /* 802.6 with an FCS */
#define TRAF_ST_VCMX_802_3       7  /* 802.3 without an FCS */
#define TRAF_ST_VCMX_802_4       8  /* 802.4 without an FCS */
#define TRAF_ST_VCMX_802_5       9  /* 802.5 without an FCS */
#define TRAF_ST_VCMX_FDDI       10  /* FDDI without an FCS */
#define TRAF_ST_VCMX_802_6      11  /* 802.6 without an FCS */
#define TRAF_ST_VCMX_FRAGMENTS  12  /* Fragments */
#define TRAF_ST_VCMX_BPDU       13  /* BPDU */

/*
 * For TRAF_LANE:
 */
#define TRAF_ST_LANE_LE_CTRL     1  /* LANE: LE Ctrl */
#define TRAF_ST_LANE_802_3       2  /* LANE: 802.3 */
#define TRAF_ST_LANE_802_5       3  /* LANE: 802.5 */
#define TRAF_ST_LANE_802_3_MC    4  /* LANE: 802.3 multicast */
#define TRAF_ST_LANE_802_5_MC    5  /* LANE: 802.5 multicast */

/*
 * For TRAF_IPSILON:
 */
#define TRAF_ST_IPSILON_FT0      1  /* Ipsilon: Flow Type 0 */
#define TRAF_ST_IPSILON_FT1      2  /* Ipsilon: Flow Type 1 */
#define TRAF_ST_IPSILON_FT2      3  /* Ipsilon: Flow Type 2 */

/**
 * @brief Pseudo-header for ATM capture files carrying cell, circuit, and AAL-layer metadata.
 */
struct atm_phdr {
    uint32_t flags;          /**< Bitmask of status flags describing capture conditions for this ATM packet. */
    uint8_t  aal;            /**< ATM Adaptation Layer type in use (e.g. AAL1, AAL2, AAL5). */
    uint8_t  type;           /**< Traffic type classification for this virtual circuit. */
    uint8_t  subtype;        /**< Traffic subtype providing further classification within @p type. */
    uint16_t vpi;            /**< Virtual Path Identifier of the ATM virtual circuit. */
    uint16_t vci;            /**< Virtual Circuit Identifier of the ATM virtual circuit. */
    uint8_t  aal2_cid;       /**< AAL2 channel identifier; only meaningful when @p aal is AAL2. */
    uint16_t channel;        /**< Link direction: 0 = DTE→DCE, 1 = DCE→DTE. */
    uint16_t cells;          /**< Number of ATM cells comprising this packet. */
    uint16_t aal5t_u2u;      /**< AAL5 User-to-User (UU) indicator field from the AAL5 CPCS trailer. */
    uint16_t aal5t_len;      /**< Length in bytes of the AAL5 CPCS-PDU payload. */
    uint32_t aal5t_chksum;   /**< CRC-32 checksum from the AAL5 CPCS trailer covering the AAL5 packet. */
};

/* Packet "pseudo-header" for the output from "wandsession", "wannext",
   "wandisplay", and similar commands on Lucent/Ascend access equipment. */

#define ASCEND_MAX_STR_LEN 64

#define ASCEND_PFX_WDS_X    1
#define ASCEND_PFX_WDS_R    2
#define ASCEND_PFX_WDD      3
#define ASCEND_PFX_ISDN_X   4
#define ASCEND_PFX_ISDN_R   5
#define ASCEND_PFX_ETHER    6

/**
 * @brief Pseudo-header for Ascend WAN capture files carrying session, call, and task metadata.
 */
struct ascend_phdr {
    uint16_t type;                        /**< Packet type identifier; one of the ASCEND_PFX_* values. */
    char     user[ASCEND_MAX_STR_LEN];    /**< Username extracted from the WAN session header; NUL-terminated. */
    uint32_t sess;                        /**< Session number extracted from the WAN session header. */
    char     call_num[ASCEND_MAX_STR_LEN];/**< Called phone number extracted from the WDD header; NUL-terminated. */
    uint32_t chunk;                       /**< Chunk number extracted from the WDD header. */
    uint32_t task;                        /**< Task number identifying the Ascend task that generated this packet. */
};

/**
 * @brief Pseudo-header for point-to-point link capture files carrying packet direction metadata.
 */
struct p2p_phdr {
    bool sent; /**< True if the packet was sent (transmitted); false if it was received. */
};

/*
 * Packet "pseudo-header" information for 802.11.
 * Radio information is only present in this form for
 * WTAP_ENCAP_IEEE_802_11_WITH_RADIO.  This is used for file formats in
 * which the radio information isn't provided as a pseudo-header in the
 * packet data.  It is also used by the dissectors for the pseudo-headers
 * in the packet data to supply radio information, in a form independent
 * of the file format and pseudo-header format, to the "802.11 radio"
 * dissector.
 *
 * Signal strength, etc. information:
 *
 * Raw signal strength can be measured in milliwatts.
 * It can also be represented as dBm, which is 10 times the log base 10
 * of the signal strength in mW.
 *
 * The Receive Signal Strength Indicator is an integer in the range 0 to 255.
 * The actual RSSI value for a given signal strength is dependent on the
 * vendor (and perhaps on the adapter).  The maximum possible RSSI value
 * is also dependent on the vendor and perhaps the adapter.
 *
 * The signal strength can be represented as a percentage, which is 100
 * times the ratio of the RSSI and the maximum RSSI.
 */

/*
 * PHY types.
 */
#define PHDR_802_11_PHY_UNKNOWN        0 /* PHY not known */
#define PHDR_802_11_PHY_11_FHSS        1 /* 802.11 FHSS */
#define PHDR_802_11_PHY_11_IR          2 /* 802.11 IR */
#define PHDR_802_11_PHY_11_DSSS        3 /* 802.11 DSSS */
#define PHDR_802_11_PHY_11B            4 /* 802.11b */
#define PHDR_802_11_PHY_11A            5 /* 802.11a */
#define PHDR_802_11_PHY_11G            6 /* 802.11g */
#define PHDR_802_11_PHY_11N            7 /* 802.11n */
#define PHDR_802_11_PHY_11AC           8 /* 802.11ac */
#define PHDR_802_11_PHY_11AD           9 /* 802.11ad */
#define PHDR_802_11_PHY_11AH          10 /* 802.11ah */
#define PHDR_802_11_PHY_11AX          11 /* 802.11ax */
#define PHDR_802_11_PHY_11BE          12 /* 802.11be - EHT */

/*
 * PHY-specific information.
 */

/**
 * @brief PHY metadata for 802.11 legacy FHSS (Frequency Hopping Spread Spectrum) captures.
 */
struct ieee_802_11_fhss {
    unsigned has_hop_set     : 1; /**< Non-zero if @p hop_set contains a valid value. */
    unsigned has_hop_pattern : 1; /**< Non-zero if @p hop_pattern contains a valid value. */
    unsigned has_hop_index   : 1; /**< Non-zero if @p hop_index contains a valid value. */

    uint8_t  hop_set;             /**< Hop set identifier used by the FHSS hopping sequence. */
    uint8_t  hop_pattern;         /**< Hop pattern identifier used by the FHSS hopping sequence. */
    uint8_t  hop_index;           /**< Hop index indicating the current position within the hopping sequence. */
};


/**
 * @brief PHY metadata for 802.11b captures.
 */
struct ieee_802_11b {
    unsigned has_short_preamble : 1; /**< Non-zero if @p short_preamble contains a valid value. */

    bool short_preamble;             /**< True if the frame was transmitted with a short PLCP preamble. */
};


/**
 * @brief PHY metadata for 802.11a captures.
 */
struct ieee_802_11a {
    unsigned has_channel_type : 1; /**< Non-zero if @p channel_type contains a valid value. */
    unsigned has_turbo_type   : 1; /**< Non-zero if @p turbo_type contains a valid value. */

    unsigned channel_type     : 2; /**< Channel type identifier indicating the 802.11a channel classification. */
    unsigned turbo_type       : 2; /**< Turbo mode type indicating whether and how proprietary turbo mode is in use. */
};

/*
 * Channel type values.
 */
#define PHDR_802_11A_CHANNEL_TYPE_NORMAL           0
#define PHDR_802_11A_CHANNEL_TYPE_HALF_CLOCKED     1
#define PHDR_802_11A_CHANNEL_TYPE_QUARTER_CLOCKED  2

/*
 * "Turbo" is an Atheros proprietary extension with 40 MHz-wide channels.
 * It can be dynamic or static.
 *
 * See
 *
 *    http://wifi-insider.com/atheros/turbo.htm
 */
#define PHDR_802_11A_TURBO_TYPE_NORMAL           0
#define PHDR_802_11A_TURBO_TYPE_TURBO            1  /* If we don't know whether it's static or dynamic */
#define PHDR_802_11A_TURBO_TYPE_DYNAMIC_TURBO    2
#define PHDR_802_11A_TURBO_TYPE_STATIC_TURBO     3

/**
 * @brief PHY metadata for 802.11g OFDM captures.
 *
 * This struct should only be used for packets transmitted using OFDM.
 * Packets sent on an 802.11g network using DSSS should use @ref ieee_802_11b
 * with the PHY type set to 802.11b instead.
 */
struct ieee_802_11g {
    unsigned has_mode : 1; /**< Non-zero if @p mode contains a valid value. */

    uint32_t mode;         /**< Proprietary extension mode flags describing vendor-specific 802.11g transmission properties. */
};

/*
 * Mode values.
 */
#define PHDR_802_11G_MODE_NORMAL    0
#define PHDR_802_11G_MODE_SUPER_G   1  /* Atheros Super G */

/**
 * @brief PHY metadata for 802.11n (HT) captures.
 */
struct ieee_802_11n {
    unsigned has_mcs_index    : 1; /**< Non-zero if @p mcs_index contains a valid value. */
    unsigned has_bandwidth    : 1; /**< Non-zero if @p bandwidth contains a valid value. */
    unsigned has_short_gi     : 1; /**< Non-zero if @p short_gi contains a valid value. */
    unsigned has_greenfield   : 1; /**< Non-zero if @p greenfield contains a valid value. */
    unsigned has_fec          : 1; /**< Non-zero if @p fec contains a valid value. */
    unsigned has_stbc_streams : 1; /**< Non-zero if @p stbc_streams contains a valid value. */
    unsigned has_ness         : 1; /**< Non-zero if @p ness contains a valid value. */

    uint16_t mcs_index;            /**< Modulation and Coding Scheme (MCS) index specifying the 802.11n data rate. */
    unsigned bandwidth;            /**< Channel bandwidth in MHz (e.g. 20, 40). */
    unsigned short_gi     : 1;     /**< True if a short guard interval (400 ns) was used; false for long guard interval (800 ns). */
    unsigned greenfield   : 1;     /**< True if the frame was transmitted in greenfield (HT-only) mode; false for mixed mode. */
    unsigned fec          : 1;     /**< Forward error correction type: 0 = BCC (Binary Convolutional Coding), 1 = LDPC. */
    unsigned stbc_streams : 2;     /**< Number of Space-Time Block Coding (STBC) spatial streams used for this transmission. */
    unsigned ness;                 /**< Number of extension spatial streams (Ness) present in the HT PPDU. */
};

/*
 * Bandwidth values; used for both 11n and 11ac.
 */
#define PHDR_802_11_BANDWIDTH_20_MHZ   0  /* 20 MHz */
#define PHDR_802_11_BANDWIDTH_40_MHZ   1  /* 40 MHz */
#define PHDR_802_11_BANDWIDTH_20_20L   2  /* 20 + 20L, 40 MHz */
#define PHDR_802_11_BANDWIDTH_20_20U   3  /* 20 + 20U, 40 MHz */
#define PHDR_802_11_BANDWIDTH_80_MHZ   4  /* 80 MHz */
#define PHDR_802_11_BANDWIDTH_40_40L   5  /* 40 + 40L MHz, 80 MHz */
#define PHDR_802_11_BANDWIDTH_40_40U   6  /* 40 + 40U MHz, 80 MHz */
#define PHDR_802_11_BANDWIDTH_20LL     7  /* ???, 80 MHz */
#define PHDR_802_11_BANDWIDTH_20LU     8  /* ???, 80 MHz */
#define PHDR_802_11_BANDWIDTH_20UL     9  /* ???, 80 MHz */
#define PHDR_802_11_BANDWIDTH_20UU     10 /* ???, 80 MHz */
#define PHDR_802_11_BANDWIDTH_160_MHZ  11 /* 160 MHz */
#define PHDR_802_11_BANDWIDTH_80_80L   12 /* 80 + 80L, 160 MHz */
#define PHDR_802_11_BANDWIDTH_80_80U   13 /* 80 + 80U, 160 MHz */
#define PHDR_802_11_BANDWIDTH_40LL     14 /* ???, 160 MHz */
#define PHDR_802_11_BANDWIDTH_40LU     15 /* ???, 160 MHz */
#define PHDR_802_11_BANDWIDTH_40UL     16 /* ???, 160 MHz */
#define PHDR_802_11_BANDWIDTH_40UU     17 /* ???, 160 MHz */
#define PHDR_802_11_BANDWIDTH_20LLL    18 /* ???, 160 MHz */
#define PHDR_802_11_BANDWIDTH_20LLU    19 /* ???, 160 MHz */
#define PHDR_802_11_BANDWIDTH_20LUL    20 /* ???, 160 MHz */
#define PHDR_802_11_BANDWIDTH_20LUU    21 /* ???, 160 MHz */
#define PHDR_802_11_BANDWIDTH_20ULL    22 /* ???, 160 MHz */
#define PHDR_802_11_BANDWIDTH_20ULU    23 /* ???, 160 MHz */
#define PHDR_802_11_BANDWIDTH_20UUL    24 /* ???, 160 MHz */
#define PHDR_802_11_BANDWIDTH_20UUU    25 /* ???, 160 MHz */

/**
 * @brief PHY metadata for 802.11ac (VHT) captures.
 */
struct ieee_802_11ac {
    unsigned has_stbc                  : 1; /**< Non-zero if @p stbc contains a valid value. */
    unsigned has_txop_ps_not_allowed   : 1; /**< Non-zero if @p txop_ps_not_allowed contains a valid value. */
    unsigned has_short_gi              : 1; /**< Non-zero if @p short_gi contains a valid value. */
    unsigned has_short_gi_nsym_disambig: 1; /**< Non-zero if @p short_gi_nsym_disambig contains a valid value. */
    unsigned has_ldpc_extra_ofdm_symbol: 1; /**< Non-zero if @p ldpc_extra_ofdm_symbol contains a valid value. */
    unsigned has_beamformed            : 1; /**< Non-zero if @p beamformed contains a valid value. */
    unsigned has_bandwidth             : 1; /**< Non-zero if @p bandwidth contains a valid value. */
    unsigned has_fec                   : 1; /**< Non-zero if @p fec contains a valid value. */
    unsigned has_group_id              : 1; /**< Non-zero if @p group_id contains a valid value. */
    unsigned has_partial_aid           : 1; /**< Non-zero if @p partial_aid contains a valid value. */

    unsigned stbc                  : 1; /**< True if all spatial streams were transmitted with Space-Time Block Coding (STBC). */
    unsigned txop_ps_not_allowed   : 1; /**< True if the TXOP Power Save mode is not permitted for this transmission. */
    unsigned short_gi              : 1; /**< True if a short guard interval (400 ns) was used; false for long guard interval (800 ns). */
    unsigned short_gi_nsym_disambig: 1; /**< True if the short GI Nsym disambiguation bit is set, indicating an extra symbol was added. */
    unsigned ldpc_extra_ofdm_symbol: 1; /**< True if an extra OFDM symbol was appended to support LDPC encoding. */
    unsigned beamformed            : 1; /**< True if the frame was transmitted using beamforming. */
    uint8_t  bandwidth;                 /**< Channel bandwidth in MHz (e.g. 20, 40, 80, 160). */
    uint8_t  mcs[4];                    /**< MCS index per user for up to 4 MU-MIMO users. */
    uint8_t  nss[4];                    /**< Number of spatial streams per user for up to 4 MU-MIMO users. */
    uint8_t  fec;                       /**< Per-user FEC type bitmask: bit set = LDPC, bit clear = BCC, for up to 4 MU-MIMO users. */
    uint8_t  group_id;                  /**< VHT group ID identifying the MU-MIMO group for this transmission. */
    uint16_t partial_aid;               /**< Partial AID (Association ID) used to identify the recipient in MU-MIMO transmissions. */
};

/*
 * 802.11ad.
 */

/*
 * Min and Max frequencies for 802.11ad and a macro for checking for 802.11ad.
 */

#define PHDR_802_11AD_MIN_FREQUENCY    57000
#define PHDR_802_11AD_MAX_FREQUENCY    71000

#define IS_80211AD(frequency) (((frequency) >= PHDR_802_11AD_MIN_FREQUENCY) &&\
                               ((frequency) <= PHDR_802_11AD_MAX_FREQUENCY))

/**
 * @brief PHY metadata for 802.11ad (WiGig/DMG) captures.
 */
struct ieee_802_11ad {
    unsigned has_mcs_index : 1; /**< Non-zero if @p mcs contains a valid value. */

    uint8_t mcs;                /**< Modulation and Coding Scheme (MCS) index specifying the 802.11ad data rate. */
};


/**
 * @brief PHY metadata for 802.11ax (HE — High Efficiency) captures.
 */
struct ieee_802_11ax {
    unsigned has_mcs_index : 1; /**< Non-zero if @p mcs contains a valid value. */
    unsigned has_bwru      : 1; /**< Non-zero if @p bwru contains a valid value. */
    unsigned has_gi        : 1; /**< Non-zero if @p gi contains a valid value. */

    uint8_t nsts : 4;           /**< Number of Space-Time Streams used for this HE transmission. */
    uint8_t mcs  : 4;           /**< Modulation and Coding Scheme (MCS) index for this HE transmission. */
    uint8_t bwru : 4;           /**< Bandwidth or Resource Unit (RU) allocation identifier. */
    uint8_t gi   : 2;           /**< Guard interval: encodes 0.8 µs, 1.6 µs, or 3.2 µs GI. */
};


/**
 * @brief Per-user PHY metadata for a single user within an 802.11be (EHT) MU transmission.
 */
struct ieee_802_11be_user_info {
    unsigned sta_id_known         : 1;  /**< Non-zero if @p sta_id contains a valid value. */
    unsigned mcs_known            : 1;  /**< Non-zero if @p mcs contains a valid value. */
    unsigned coding_known         : 1;  /**< Non-zero if @p ldpc_coding contains a valid value. */
    unsigned rsv_known            : 1;  /**< Non-zero if @p rsv contains a valid value. */
    unsigned nsts_known           : 1;  /**< Non-zero if @p nsts contains a valid value. */
    unsigned bf_known             : 1;  /**< Non-zero if @p beamform contains a valid value. */
    unsigned spatial_config_known : 1;  /**< Non-zero if spatial configuration information is valid for this user. */
    unsigned data_for_this_user   : 1;  /**< Non-zero if this EHT PPDU carries data intended for this user. */
    unsigned sta_id               : 11; /**< Association ID (partial) identifying this MU-MIMO user. */
    unsigned ldpc_coding          : 1;  /**< Forward error correction type: 0 = BCC, 1 = LDPC. */
    unsigned mcs                  : 4;  /**< Modulation and Coding Scheme (MCS) index assigned to this user. */
    unsigned nsts                 : 4;  /**< Number of Space-Time Streams assigned to this user. */
    unsigned rsv                  : 1;  /**< Reserved bit. */
    unsigned beamform             : 1;  /**< Non-zero if beamforming was applied for this user. */
    unsigned rsv2                 : 2;  /**< Reserved bits. */
};

#define PHDR_802_11BE_MAX_USERS 4 /**< Maximum number of MU-MIMO users described in an 802.11be PHY metadata record. */

/**
 * @brief PHY metadata for 802.11be (EHT — Extremely High Throughput) captures.
 */
struct ieee_802_11be {
    unsigned has_ru_mru_size : 1; /**< Non-zero if @p ru_mru_size contains a valid value. */
    unsigned has_gi          : 1; /**< Non-zero if @p gi contains a valid value. */
    unsigned has_bandwidth   : 1; /**< Non-zero if @p bandwidth contains a valid value. */

    uint8_t bandwidth;            /**< Channel bandwidth in MHz (e.g. 20, 40, 80, 160, 320). */
    uint8_t ru_mru_size : 4;      /**< Resource Unit (RU) or Multi-RU (MRU) allocation size identifier. */
    uint8_t gi          : 2;      /**< Guard interval: encodes 0.8 µs, 1.6 µs, or 3.2 µs GI. */
    uint8_t num_users;            /**< Number of valid entries in the @p user array; at most PHDR_802_11BE_MAX_USERS. */
    struct ieee_802_11be_user_info user[PHDR_802_11BE_MAX_USERS]; /**< Per-user PHY metadata for up to PHDR_802_11BE_MAX_USERS MU-MIMO users. */
};


/**
 * @brief Union representing physical layer information for IEEE 802.11 variants.
 *
 * This union encapsulates PHY-specific metadata for various 802.11 standards,
 * allowing parsers or analyzers to interpret modulation, channel, and timing
 * details based on the active wireless technology.
 *
 * Each member corresponds to a specific PHY type, such as FHSS, DSSS, OFDM,
 * or advanced MIMO schemes used in newer standards.
 */
union ieee_802_11_phy_info {
    struct ieee_802_11_fhss info_11_fhss; /**< Frequency-Hopping Spread Spectrum (802.11-1997). */
    struct ieee_802_11b    info_11b;      /**< Direct Sequence Spread Spectrum (802.11b). */
    struct ieee_802_11a    info_11a;      /**< OFDM-based PHY (802.11a). */
    struct ieee_802_11g    info_11g;      /**< Extended OFDM PHY (802.11g). */
    struct ieee_802_11n    info_11n;      /**< High Throughput PHY (802.11n). */
    struct ieee_802_11ac   info_11ac;     /**< Very High Throughput PHY (802.11ac). */
    struct ieee_802_11ad   info_11ad;     /**< 60 GHz PHY (802.11ad). */
    struct ieee_802_11ax   info_11ax;     /**< High Efficiency PHY (802.11ax). */
    struct ieee_802_11be   info_11be;     /**< Extremely High Throughput PHY (802.11be). */
};

/**
 * @brief Pseudo-header for 802.11 wireless capture files carrying full PHY, signal, and frame metadata.
 */
struct ieee_802_11_phdr {
    int      fcs_len;                       /**< Number of bytes of FCS appended to the frame; -1 if unknown. */
    unsigned decrypted                : 1;  /**< True if the frame has been decrypted despite the 802.11 "Protected" flag being set. */
    unsigned datapad                  : 1;  /**< True if padding bytes are present between the 802.11 header and the payload. */
    unsigned no_a_msdus               : 1;  /**< True if the A-MSDU subframe bit in the QoS Control field should be ignored. */
    unsigned phy;                           /**< PHY type identifier indicating the 802.11 physical layer variant (e.g. 802.11a/b/g/n/ac/ax). */
    union ieee_802_11_phy_info phy_info;    /**< PHY-specific metadata corresponding to the @p phy type. */

    unsigned has_channel              : 1;  /**< Non-zero if @p channel contains a valid value. */
    unsigned has_frequency            : 1;  /**< Non-zero if @p frequency contains a valid value. */
    unsigned has_data_rate            : 1;  /**< Non-zero if @p data_rate contains a valid value. */
    unsigned has_signal_percent       : 1;  /**< Non-zero if @p signal_percent contains a valid value. */
    unsigned has_noise_percent        : 1;  /**< Non-zero if @p noise_percent contains a valid value. */
    unsigned has_signal_dbm           : 1;  /**< Non-zero if @p signal_dbm contains a valid value. */
    unsigned has_noise_dbm            : 1;  /**< Non-zero if @p noise_dbm contains a valid value. */
    unsigned has_signal_db            : 1;  /**< Non-zero if @p signal_db contains a valid value. */
    unsigned has_noise_db             : 1;  /**< Non-zero if @p noise_db contains a valid value. */
    unsigned has_tsf_timestamp        : 1;  /**< Non-zero if @p tsf_timestamp contains a valid value. */
    unsigned has_aggregate_info       : 1;  /**< Non-zero if @p aggregate_flags and @p aggregate_id contain valid values. */
    unsigned has_zero_length_psdu_type: 1;  /**< Non-zero if @p zero_length_psdu_type contains a valid value. */

    uint16_t channel;                       /**< 802.11 channel number on which this frame was captured. */
    uint32_t frequency;                     /**< Center frequency in MHz of the channel on which this frame was captured. */
    uint16_t data_rate;                     /**< Data rate at which this frame was transmitted, in units of 500 Kb/s. */
    uint8_t  signal_percent;                /**< Received signal level expressed as a percentage of the maximum. */
    uint8_t  noise_percent;                 /**< Noise level expressed as a percentage of the maximum. */
    int8_t   signal_dbm;                    /**< Received signal level in dBm. */
    int8_t   noise_dbm;                     /**< Noise level in dBm. */
    uint8_t  signal_db;                     /**< Received signal level in dB relative to an arbitrary reference point. */
    uint8_t  noise_db;                      /**< Noise level in dB relative to an arbitrary reference point. */
    uint64_t tsf_timestamp;                 /**< 802.11 Timing Synchronization Function (TSF) timer value at the time of capture, in microseconds. */
    uint32_t aggregate_flags;               /**< A-MPDU aggregation flags describing the role of this frame within the aggregate. */
    uint32_t aggregate_id;                  /**< A-MPDU aggregate identifier used to group subframes for reassembly. */
    uint8_t  zero_length_psdu_type;         /**< Type code of the zero-length PSDU, used for sounding and NDP frames. */
};

/*
 * A-MPDU flags.
 */
#define PHDR_802_11_LAST_PART_OF_A_MPDU    0x00000001 /* this is the last part of an A-MPDU */
#define PHDR_802_11_A_MPDU_DELIM_CRC_ERROR 0x00000002 /* delimiter CRC error after this part */

/*
 * Zero-length PSDU types.
 */
#define PHDR_802_11_SOUNDING_PSDU                 0 /* sounding PPDU */
#define PHDR_802_11_DATA_NOT_CAPTURED             1 /* data not captured, (e.g. multi-user PPDU) */
#define PHDR_802_11_0_LENGTH_PSDU_VENDOR_SPECIFIC 0xff

/* Packet "pseudo-header" for the output from CoSine L2 debug output. */

#define COSINE_MAX_IF_NAME_LEN  128

#define COSINE_ENCAP_TEST      1
#define COSINE_ENCAP_PPoATM    2
#define COSINE_ENCAP_PPoFR     3
#define COSINE_ENCAP_ATM       4
#define COSINE_ENCAP_FR        5
#define COSINE_ENCAP_HDLC      6
#define COSINE_ENCAP_PPP       7
#define COSINE_ENCAP_ETH       8
#define COSINE_ENCAP_UNKNOWN  99

#define COSINE_DIR_TX 1
#define COSINE_DIR_RX 2

/**
 * @brief Pseudo-header for CoSine Systems capture files carrying encapsulation, direction, and QoS metadata.
 */
struct cosine_phdr {
    uint8_t  encap;                           /**< Encapsulation type of this packet; one of the COSINE_ENCAP_* values. */
    uint8_t  direction;                       /**< Packet direction; one of the COSINE_DIR_* values. */
    char     if_name[COSINE_MAX_IF_NAME_LEN]; /**< NUL-terminated encapsulation and logical interface name string. */
    uint16_t pro;                             /**< Protocol identifier associated with this packet. */
    uint16_t off;                             /**< Offset value associated with this packet's encapsulation layer. */
    uint16_t pri;                             /**< Priority level assigned to this packet for QoS processing. */
    uint16_t rm;                              /**< Rate Marking value applied to this packet for traffic shaping. */
    uint16_t err;                             /**< Error code reported by the CoSine device for this packet; 0 if no error. */
};

/* Packet "pseudo-header" for IrDA capture files. */

/*
 * Direction of the packet
 */
#define IRDA_INCOMING       0x0000
#define IRDA_OUTGOING       0x0004

/*
 * "Inline" log messages produced by IrCOMM2k on Windows
 */
#define IRDA_LOG_MESSAGE    0x0100  /* log message */
#define IRDA_MISSED_MSG     0x0101  /* missed log entry or frame */

/*
 * Differentiate between frames and log messages
 */
#define IRDA_CLASS_FRAME    0x0000
#define IRDA_CLASS_LOG      0x0100
#define IRDA_CLASS_MASK     0xFF00

/**
 * @brief Pseudo-header carrying IrDA packet type metadata for captured IrDA frames.
 */
struct irda_phdr {
    uint16_t pkttype;  /**< IrDA packet type identifier classifying the captured frame (e.g., log message, data frame). */
};

/**
 * @brief Pseudo-header for HP-UX nettl capture files carrying subsystem, device, and process metadata.
 */
struct nettl_phdr {
    uint16_t subsys; /**< Subsystem identifier indicating the HP-UX network layer or driver that captured this packet. */
    uint32_t devid;  /**< Device identifier of the network interface that captured this packet. */
    uint32_t kind;   /**< Kind flags describing the type and direction of this capture record. */
    int32_t  pid;    /**< Process identifier (PID) of the process associated with this packet; -1 if not applicable. */
    uint32_t uid;    /**< User identifier (UID) of the user associated with this packet. */
};

/* Packet "pseudo-header" for MTP2 files. */

#define MTP2_ANNEX_A_NOT_USED      0
#define MTP2_ANNEX_A_USED          1
#define MTP2_ANNEX_A_USED_UNKNOWN  2

/**
 * @brief Pseudo-header carrying MTP2 link metadata for captured SS7 MTP2 frames.
 */
struct mtp2_phdr {
    uint8_t  sent;           /**< Non-zero if this frame was transmitted (sent); zero if it was received. */
    uint8_t  annex_a_used;   /**< Non-zero if MTP2 Annex A (FISU/LSSU extensions) was used on this link. */
    uint16_t link_number;    /**< Identifies the MTP2 signalling link that carried this frame. */
};

/**
 * @brief Pseudo-header metadata for packets in K12 capture files.
 *
 * This union provides additional per-packet context for K12-formatted captures,
 * typically used in telecom and voice-over-circuit environments. It supports
 * both ATM and DS0-based framing.
 */
typedef union {
    /**
     * @brief ATM-specific channel identifiers.
     *
     * Used when the packet is associated with an ATM virtual circuit.
     */
    struct {
        uint16_t vp;  /**< Virtual Path Identifier (VPI). */
        uint16_t vc;  /**< Virtual Channel Identifier (VCI). */
        uint16_t cid; /**< Channel Identifier. */
    } atm;

    /**
     * @brief DS0 channel bitmask.
     *
     * Used when the packet is associated with a TDM (Time Division Multiplexing)
     * DS0 channel. Each bit represents an active timeslot.
     */
    uint32_t ds0mask;
} k12_input_info_t;

/**
 * @brief Pseudo-header for Tektronix K12 capture files carrying input port, stack, and protocol metadata.
 */
struct k12_phdr {
    uint32_t         input;        /**< Numeric identifier of the K12 input port on which this packet was captured. */
    const char      *input_name;   /**< Human-readable name of the input port; NULL if unavailable. */
    const char      *stack_file;   /**< Path to the K12 stack configuration file associated with this input; NULL if unavailable. */
    uint32_t         input_type;   /**< Type identifier describing the protocol stack or medium of the input port. */
    k12_input_info_t input_info;   /**< Protocol-specific input configuration details corresponding to @p input_type. */
    uint8_t         *extra_info;   /**< Pointer to additional raw metadata bytes associated with this packet; NULL if none. */
    uint32_t         extra_length; /**< Length in bytes of the data pointed to by @p extra_info; 0 if none. */
    void            *stuff;        /**< Opaque pointer to internal K12 reader state associated with this input port. */
};

#define K12_PORT_DS0S      0x00010008
#define K12_PORT_DS1       0x00100008
#define K12_PORT_ATMPVC    0x01020000

/**
 * @brief LAPD pseudo-header for packet metadata.
 *
 * This structure provides minimal metadata for LAPD (Link Access Procedure for the D channel)
 * packets, typically used in ISDN signaling. It may be used to distinguish packet types
 * and network direction.
 */
struct lapd_phdr {
    uint16_t pkttype;    /**< LAPD packet type identifier. */
    uint8_t we_network;  /**< Direction flag: true if packet is from the network side. */
};

/**
 * @brief Pseudo-header for Catapult DCT2000 captures.
 *
 * This structure wraps protocol-specific pseudo-headers for ISDN, ATM, or P2P traffic,
 * along with file offset and capture context. It is used to interpret packets in
 * Catapult DCT2000 trace files.
 */
struct catapult_dct2000_phdr {
    union {
        struct isdn_phdr isdn; /**< ISDN-specific pseudo-header. */
        struct atm_phdr  atm;  /**< ATM-specific pseudo-header. */
        struct p2p_phdr  p2p;  /**< Point-to-point pseudo-header. */
    } inner_pseudo_header;

    int64_t seek_off;     /**< File offset of the packet within the capture. */
    struct wtap *wth;     /**< Pointer to the capture context (Wiretap handle). */
};

/**
 * @brief Pseudo-header for Endace ERF (Extensible Record Format) capture files carrying timestamp and record metadata.
 */
struct erf_phdr {
    uint64_t ts;    /**< ERF timestamp in Endace's 64-bit fixed-point format: upper 32 bits are seconds since 1970-01-01, lower 32 bits are fractional seconds. */
    uint8_t  type;  /**< ERF record type identifying the physical medium and encapsulation of this record. */
    uint8_t  flags; /**< Bitmask of ERF flags describing capture conditions such as RX/TX direction and loss indicators. */
    uint16_t rlen;  /**< Record length in bytes including this header, extension headers, any subheader, and the payload. */
    uint16_t lctr;  /**< Loss counter; incremented by the capture hardware each time one or more records are dropped. */
    uint16_t wlen;  /**< Wire length in bytes of the original packet as observed on the network. */
};

/**
 * @brief Holds a single ERF extension header word appended after the main ERF header.
 */
struct erf_ehdr {
    uint64_t ehdr; /**< Raw 64-bit extension header value; the type and continuation bit are encoded in the most significant byte. */
};

#define MAX_ERF_EHDR 16 /**< Maximum number of ERF extension headers that may be present in a single ERF record. */

/**
 * @brief ERF Ethernet subheader providing the frame offset for Ethernet ERF records.
 */
struct wtap_erf_eth_hdr {
    uint8_t offset; /**< Byte offset from the start of the captured data to the first byte of the Ethernet frame. */
    uint8_t pad;    /**< Padding byte to align the subheader to a 2-byte boundary; must be zero. */
};

/**
 * @brief Extended pseudo-header for ERF multi-channel (MC) packet records.
 *
 * This structure builds on the basic ERF header to support multi-channel
 * packet formats, including optional extended headers and protocol-specific
 * subheaders. It is used in advanced ERF capture scenarios such as DAG cards
 * with multiple input streams or specialized framing.
 */
struct erf_mc_phdr {
    struct erf_phdr phdr; /**< Base ERF header containing timestamp, type, and length metadata. */

    struct erf_ehdr ehdr_list[MAX_ERF_EHDR]; /**< Array of extended ERF headers (e.g., channel, color, hash). */

    /**
     * @brief Protocol-specific subheader union.
     *
     * Contains additional metadata depending on the ERF record type.
     */
    union {
        struct wtap_erf_eth_hdr eth_hdr; /**< Ethernet-specific subheader. */
        uint32_t mc_hdr;                 /**< Multi-channel header value. */
        uint32_t aal2_hdr;               /**< AAL2-specific header value. */
    } subhdr;
};

#define SITA_FRAME_DIR_TXED            (0x00)  /* values of sita_phdr.flags */
#define SITA_FRAME_DIR_RXED            (0x01)
#define SITA_FRAME_DIR                 (0x01)  /* mask */
#define SITA_ERROR_NO_BUFFER           (0x80)

#define SITA_SIG_DSR                   (0x01)  /* values of sita_phdr.signals */
#define SITA_SIG_DTR                   (0x02)
#define SITA_SIG_CTS                   (0x04)
#define SITA_SIG_RTS                   (0x08)
#define SITA_SIG_DCD                   (0x10)
#define SITA_SIG_UNDEF1                (0x20)
#define SITA_SIG_UNDEF2                (0x40)
#define SITA_SIG_UNDEF3                (0x80)

#define SITA_ERROR_TX_UNDERRUN         (0x01)  /* values of sita_phdr.errors2 (if SITA_FRAME_DIR_TXED) */
#define SITA_ERROR_TX_CTS_LOST         (0x02)
#define SITA_ERROR_TX_UART_ERROR       (0x04)
#define SITA_ERROR_TX_RETX_LIMIT       (0x08)
#define SITA_ERROR_TX_UNDEF1           (0x10)
#define SITA_ERROR_TX_UNDEF2           (0x20)
#define SITA_ERROR_TX_UNDEF3           (0x40)
#define SITA_ERROR_TX_UNDEF4           (0x80)

#define SITA_ERROR_RX_FRAMING          (0x01)  /* values of sita_phdr.errors1 (if SITA_FRAME_DIR_RXED) */
#define SITA_ERROR_RX_PARITY           (0x02)
#define SITA_ERROR_RX_COLLISION        (0x04)
#define SITA_ERROR_RX_FRAME_LONG       (0x08)
#define SITA_ERROR_RX_FRAME_SHORT      (0x10)
#define SITA_ERROR_RX_UNDEF1           (0x20)
#define SITA_ERROR_RX_UNDEF2           (0x40)
#define SITA_ERROR_RX_UNDEF3           (0x80)

#define SITA_ERROR_RX_NONOCTET_ALIGNED (0x01)  /* values of sita_phdr.errors2 (if SITA_FRAME_DIR_RXED) */
#define SITA_ERROR_RX_ABORT            (0x02)
#define SITA_ERROR_RX_CD_LOST          (0x04)
#define SITA_ERROR_RX_DPLL             (0x08)
#define SITA_ERROR_RX_OVERRUN          (0x10)
#define SITA_ERROR_RX_FRAME_LEN_VIOL   (0x20)
#define SITA_ERROR_RX_CRC              (0x40)
#define SITA_ERROR_RX_BREAK            (0x80)

#define SITA_PROTO_UNUSED              (0x00)  /* values of sita_phdr.proto */
#define SITA_PROTO_BOP_LAPB            (0x01)
#define SITA_PROTO_ETHERNET            (0x02)
#define SITA_PROTO_ASYNC_INTIO         (0x03)
#define SITA_PROTO_ASYNC_BLKIO         (0x04)
#define SITA_PROTO_ALC                 (0x05)
#define SITA_PROTO_UTS                 (0x06)
#define SITA_PROTO_PPP_HDLC            (0x07)
#define SITA_PROTO_SDLC                (0x08)
#define SITA_PROTO_TOKENRING           (0x09)
#define SITA_PROTO_I2C                 (0x10)
#define SITA_PROTO_DPM_LINK            (0x11)
#define SITA_PROTO_BOP_FRL             (0x12)

/**
 * @brief Pseudo-header for SITA WAN capture files carrying signal, error, and protocol metadata.
 */
struct sita_phdr {
    uint8_t sita_flags;    /**< Bitmask of SITA capture flags describing the state and direction of this frame. */
    uint8_t sita_signals;  /**< Bitmask of physical signal line states (e.g. RTS, CTS, DSR, DTR) at the time of capture. */
    uint8_t sita_errors1;  /**< First bitmask of hardware-reported error conditions for this frame. */
    uint8_t sita_errors2;  /**< Second bitmask of hardware-reported error conditions for this frame. */
    uint8_t sita_proto;    /**< Protocol identifier indicating the WAN protocol encapsulated in this frame. */
};

/**
 * @brief Pseudo-header for Bluetooth HCI capture files carrying direction and channel metadata.
 */
struct bthci_phdr {
    bool     sent;    /**< True if the HCI frame was sent from the host to the controller; false if received from the controller. */
    uint32_t channel; /**< HCI channel identifier indicating the logical transport on which this frame was exchanged. */
};

#define BTHCI_CHANNEL_COMMAND  1
#define BTHCI_CHANNEL_ACL      2
#define BTHCI_CHANNEL_SCO      3
#define BTHCI_CHANNEL_EVENT    4
#define BTHCI_CHANNEL_ISO      5

/**
 * @brief Pseudo-header for Linux Bluetooth Monitor (WTAP_ENCAP_BLUETOOTH_LINUX_MONITOR) capture files.
 */
struct btmon_phdr {
    uint16_t adapter_id; /**< Index of the Bluetooth adapter associated with this HCI event or data frame. */
    uint16_t opcode;     /**< Linux Bluetooth Monitor opcode identifying the type of this monitor record. */
};

/**
 * @brief Pseudo-header for layer 1 event (WTAP_ENCAP_LAYER1_EVENT) capture files carrying signal direction metadata.
 */
struct l1event_phdr {
    bool uton; /**< True if the layer 1 event was in the user-to-network direction; false for network-to-user. */
};

/**
 * @brief Pseudo-header for I2C bus capture files carrying bus number, event type, and flag metadata.
 */
struct i2c_phdr {
    uint8_t  is_event; /**< Non-zero if this record represents an I2C bus event rather than a data transfer. */
    uint8_t  bus;      /**< I2C bus number on which this transfer or event was captured. */
    uint32_t flags;    /**< Bitmask of I2C capture flags describing transfer properties and error conditions. */
};

/**
 * @brief Pseudo-header for GSM Um air interface (WTAP_ENCAP_GSM_UM) capture files.
 */
struct gsm_um_phdr {
    bool     uplink;      /**< True if the frame was captured on the uplink (MS→BTS); false for downlink (BTS→MS). */
    uint8_t  channel;     /**< Logical channel type on which this frame was captured (e.g. BCCH, SDCCH, TCH). */
    /* The following are only populated for downlink */
    uint8_t  bsic;        /**< Base Station Identity Code of the BTS; populated for downlink frames only. */
    uint16_t arfcn;       /**< Absolute Radio Frequency Channel Number of the carrier; populated for downlink frames only. */
    uint32_t tdma_frame;  /**< TDMA frame number at which this frame was captured; populated for downlink frames only. */
    uint8_t  error;       /**< Error code reported by the capture device for this frame; 0 if no error. */
    uint16_t timeshift;   /**< Timing offset in quarter-symbol units measured for this frame. */
};

#define GSM_UM_CHANNEL_UNKNOWN  0
#define GSM_UM_CHANNEL_BCCH     1
#define GSM_UM_CHANNEL_SDCCH    2
#define GSM_UM_CHANNEL_SACCH    3
#define GSM_UM_CHANNEL_FACCH    4
#define GSM_UM_CHANNEL_CCCH     5
#define GSM_UM_CHANNEL_RACH     6
#define GSM_UM_CHANNEL_AGCH     7
#define GSM_UM_CHANNEL_PCH      8

/**
 * @brief Pseudo-header for Citrix NetScaler nstrace capture files carrying field offset and record layout metadata.
 */
struct nstr_phdr {
    int64_t  rec_offset;            /**< Byte offset of this record within the nstrace capture file. */
    int32_t  rec_len;               /**< Total length in bytes of this capture record. */
    uint8_t  nicno_offset;          /**< Byte offset within the record to the NIC number field. */
    uint8_t  nicno_len;             /**< Length in bytes of the NIC number field. */
    uint8_t  dir_offset;            /**< Byte offset within the record to the packet direction field. */
    uint8_t  dir_len;               /**< Length in bytes of the packet direction field. */
    uint16_t eth_offset;            /**< Byte offset within the record to the start of the Ethernet frame data. */
    uint8_t  pcb_offset;            /**< Byte offset within the record to the primary Protocol Control Block (PCB) pointer field. */
    uint8_t  l_pcb_offset;          /**< Byte offset within the record to the linked Protocol Control Block (PCB) pointer field. */
    uint8_t  rec_type;              /**< Record type identifier indicating the format and content of this nstrace record. */
    uint8_t  vlantag_offset;        /**< Byte offset within the record to the VLAN tag field. */
    uint8_t  coreid_offset;         /**< Byte offset within the record to the CPU core ID field. */
    uint8_t  srcnodeid_offset;      /**< Byte offset within the record to the source cluster node ID field. */
    uint8_t  destnodeid_offset;     /**< Byte offset within the record to the destination cluster node ID field. */
    uint8_t  clflags_offset;        /**< Byte offset within the record to the cluster flags field. */
    uint8_t  src_vmname_len_offset; /**< Byte offset within the record to the source VM name length field. */
    uint8_t  dst_vmname_len_offset; /**< Byte offset within the record to the destination VM name length field. */
    uint8_t  ns_activity_offset;    /**< Byte offset within the record to the NetScaler activity flags field. */
    uint8_t  data_offset;           /**< Byte offset within the record to the start of the packet payload data. */
};

/**
 * @brief Pseudo-header for Nokia firewall capture files, extending the Ethernet pseudo-header with device-specific metadata.
 */
struct nokia_phdr {
    struct eth_phdr eth;   /**< Standard Ethernet pseudo-header carrying FCS length metadata. */
    uint8_t stuff[4];      /**< Device-specific metadata of unknown purpose appended by Nokia firmware. */
};

#define LLCP_PHDR_FLAG_SENT 0 /**< Flag value indicating the LLCP frame was sent by the local device. */

/**
 * @brief Pseudo-header for NFC Logical Link Control Protocol (LLCP) capture files.
 */
struct llcp_phdr {
    uint8_t adapter; /**< Index of the NFC adapter on which this LLCP frame was captured. */
    uint8_t flags;   /**< Bitmask of LLCP capture flags; LLCP_PHDR_FLAG_SENT indicates a sent frame. */
};

/**
 * @brief Pseudo-header for Android Logcat (WTAP_ENCAP_LOGCAT) capture files.
 */
struct logcat_phdr {
    int version; /**< Logcat binary format version identifying the record layout (e.g. 1, 2, 3, or 4). */
};

/**
 * @brief Pseudo-header metadata for packets captured in NetMon (Network Monitor) files.
 *
 * This structure provides supplemental information for each packet in a NetMon capture,
 * including user-defined comments and protocol-specific subheaders. It is used to
 * enrich packet display and analysis in tools that support NetMon format.
 */
struct netmon_phdr {
    uint8_t* title;       /**< Comment title, stored as a null-terminated UTF-8 string. */
    uint32_t descLength;  /**< Length in bytes of the comment description. */
    uint8_t* description; /**< Comment description, formatted in ASCII RTF. */

    unsigned sub_encap;   /**< Actual encapsulation type used for the packet (e.g., Ethernet, ATM). */

    /**
     * @brief Protocol-specific subheader union.
     *
     * Contains metadata relevant to the encapsulated protocol.
     */
    union sub_wtap_pseudo_header {
        struct eth_phdr eth;               /**< Ethernet pseudo-header. */
        struct atm_phdr atm;               /**< ATM pseudo-header. */
        struct ieee_802_11_phdr ieee_802_11; /**< IEEE 802.11 wireless pseudo-header. */
    } subheader;
};

/* Record "pseudo-header" information for header data from MS ProcMon files. */

struct procmon_process_t;

/**
 * @brief Pseudo-header for Microsoft ProcMon (Process Monitor) captures.
 */
struct procmon_phdr {
    uint32_t                 *process_index_map;      /**< Map from raw process index to @c process_array index. */
    size_t                    process_index_map_size; /**< Number of entries in @c process_index_map. */
    struct procmon_process_t *process_array;          /**< Array of captured process descriptors. */
    size_t                    process_array_size;     /**< Number of entries in @c process_array. */
    bool                      system_bitness;         /**< True if the captured system was 64-bit, false if 32-bit. */
};


/**
 * @brief Pseudo-header for BER (Basic Encoding Rules) data files.
 */
struct ber_phdr {
    const char *pathname; /**< Path name of the BER-encoded source file. */
};


/**
 * @brief Pseudo-header for M-Module binary files.
 */
struct mmodule_phdr {
    uint8_t chunktype; /**< M-Module chunk type identifier. */
};

/**
 * @brief Top-level union of all Wiretap pseudo-headers.
 *
 * Exactly one member is valid per record, selected by the encapsulation
 * type (@c wtap_packet_header.pkt_encap) or record type.
 */
union wtap_pseudo_header {
    struct eth_phdr              eth;         /**< Ethernet pseudo-header. */
    struct dte_dce_phdr          dte_dce;     /**< DTE/DCE serial pseudo-header. */
    struct isdn_phdr             isdn;        /**< ISDN pseudo-header. */
    struct atm_phdr              atm;         /**< ATM pseudo-header. */
    struct ascend_phdr           ascend;      /**< Lucent/Ascend WAN pseudo-header. */
    struct p2p_phdr              p2p;         /**< Point-to-point pseudo-header. */
    struct ieee_802_11_phdr      ieee_802_11; /**< IEEE 802.11 wireless pseudo-header. */
    struct cosine_phdr           cosine;      /**< CoSine IPNOS pseudo-header. */
    struct irda_phdr             irda;        /**< IrDA pseudo-header. */
    struct nettl_phdr            nettl;       /**< HP-UX nettl pseudo-header. */
    struct mtp2_phdr             mtp2;        /**< MTP2 pseudo-header. */
    struct k12_phdr              k12;         /**< Tektronix K12 pseudo-header. */
    struct lapd_phdr             lapd;        /**< LAPD pseudo-header. */
    struct catapult_dct2000_phdr dct2000;     /**< Catapult DCT2000 pseudo-header. */
    struct erf_mc_phdr           erf;         /**< Endace ERF (multi-channel) pseudo-header. */
    struct sita_phdr             sita;        /**< SITA WAN pseudo-header. */
    struct bthci_phdr            bthci;       /**< Bluetooth HCI pseudo-header. */
    struct btmon_phdr            btmon;       /**< Bluetooth Linux Monitor pseudo-header. */
    struct l1event_phdr          l1event;     /**< Layer 1 event pseudo-header. */
    struct i2c_phdr              i2c;         /**< I2C pseudo-header. */
    struct gsm_um_phdr           gsm_um;      /**< GSM Um (air interface) pseudo-header. */
    struct nstr_phdr             nstr;        /**< NetScaler nstrace pseudo-header. */
    struct nokia_phdr            nokia;       /**< Nokia pseudo-header. */
    struct llcp_phdr             llcp;        /**< NFC LLCP pseudo-header. */
    struct logcat_phdr           logcat;      /**< Android logcat pseudo-header. */
    struct netmon_phdr           netmon;      /**< Microsoft NetMon pseudo-header. */
    struct procmon_phdr          procmon;     /**< Microsoft ProcMon pseudo-header. */
    struct ber_phdr              ber;         /**< BER file pseudo-header. */
    struct mmodule_phdr          mmodule;     /**< M-Module pseudo-header. */
};

/*
 * Record type values.
 *
 * This list will expand over time, so don't assume everything will
 * forever be one of the types listed below.
 *
 * For file-type-specific records, the "ftsrec" field of the pseudo-header
 * contains a file-type-specific subtype value, such as a block type for
 * a pcapng file.
 *
 * An "event" is an indication that something happened during the capture
 * process, such as a status transition of some sort on the network.
 * These should, ideally, have a time stamp and, if they're relevant to
 * a particular interface on a multi-interface capture, should also have
 * an interface ID.  The data for the event is file-type-specific and
 * subtype-specific.  These should be dissected and displayed just as
 * packets are.
 *
 * A "report" supplies information not corresponding to an event;
 * for example, a pcapng Interface Statistics Block would be a report,
 * as it doesn't correspond to something happening on the network.
 * They may have a time stamp, and should be dissected and displayed
 * just as packets are.
 *
 * We distinguish between "events" and "reports" so that, for example,
 * the packet display can show the delta between a packet and an event
 * but not show the delta between a packet and a report, as the time
 * stamp of a report may not correspond to anything interesting on
 * the network but the time stamp of an event would.
 *
 * XXX - are there any file-type-specific records that *shouldn't* be
 * dissected and displayed?  If so, they should be parsed and the
 * information in them stored somewhere, and used somewhere, whether
 * it's just used when saving the file in its native format or also
 * used to parse *other* file-type-specific records.
 *
 * These would be similar to, for example, pcapng Interface Description
 * Blocks, for which the position within the file is significant only
 * in that an IDB for an interface must appear before any packets from
 * the interface; the fact that an IDB appears at some point doesn't
 * necessarily mean something happened in the capture at that point.
 * Name Resolution Blocks are another example of such a record.
 *
 * (XXX - if you want to have a record that says "this interface first
 * showed up at this time", that needs to be a separate record type
 * from the IDB.  We *could* add a "New Interface Description Block",
 * with a time stamp, for that purpose, but we'd *still* have to
 * provide IDBs for those interfaces, for compatibility with programs
 * that don't know about the NIDB.  An ISB with only an isb_starttime
 * option would suffice for this purpose, so nothing needs to be
 * added to pcapng for this.)
 */
#define REC_TYPE_PACKET                 0    /**< packet */
#define REC_TYPE_FT_SPECIFIC_EVENT      1    /**< file-type-specific event */
#define REC_TYPE_FT_SPECIFIC_REPORT     2    /**< file-type-specific report */
#define REC_TYPE_SYSCALL                3    /**< system call */
#define REC_TYPE_SYSTEMD_JOURNAL_EXPORT 4    /**< systemd journal entry */
#define REC_TYPE_CUSTOM_BLOCK           5    /**< pcapng custom block */

/**
 * @brief Header metadata for a captured network packet.
 */
typedef struct {
    uint32_t caplen;      /**< Number of bytes stored in the capture file for this packet. */
    uint32_t len;         /**< Original packet length as seen on the wire. */
    int      pkt_encap;   /**< Encapsulation type (@c WTAP_ENCAP_*) identifying the link layer for this packet. */
    uint32_t interface_id; /**< pcapng interface ID that captured this packet. */

    union wtap_pseudo_header pseudo_header; /**< Encapsulation-specific metadata; active member selected by @c pkt_encap. */
} wtap_packet_header;

/*
 * The pcapng specification says "The word is encoded as an unsigned
 * 32-bit integer, using the endianness of the Section Header Block
 * scope it is in. In the following table, the bits are numbered with
 * 0 being the most-significant bit and 31 being the least-significant
 * bit of the 32-bit unsigned integer."
 *
 * From that, the direction, in bits 0 and 1, is at the *top* of the word.
 *
 * However, several implementations, such as:
 *
 *   the Wireshark pcapng file reading code;
 *
 *   macOS libpcap and tcpdump;
 *
 *   text2pcap;
 *
 *   and probably the software that generated the capture in bug 11665;
 *
 * treat 0 as the *least*-significant bit and bit 31 being the *most*-
 * significant bit of the flags word, and put the direction at the
 * *bottom* of the word.
 *
 * For now, we go with the known implementations.
 */

/* Direction field of the packet flags */
#define PACK_FLAGS_DIRECTION_MASK     0x00000003 /* unshifted */
#define PACK_FLAGS_DIRECTION_SHIFT    0
#define PACK_FLAGS_DIRECTION(pack_flags) (((pack_flags) & PACK_FLAGS_DIRECTION_MASK) >> PACK_FLAGS_DIRECTION_SHIFT)
#define PACK_FLAGS_DIRECTION_UNKNOWN  0
#define PACK_FLAGS_DIRECTION_INBOUND  1
#define PACK_FLAGS_DIRECTION_OUTBOUND 2

/* Reception type field of the packet flags */
#define PACK_FLAGS_RECEPTION_TYPE_MASK        0x0000001C /* unshifted */
#define PACK_FLAGS_RECEPTION_TYPE_SHIFT       2
#define PACK_FLAGS_RECEPTION_TYPE(pack_flags) (((pack_flags) & PACK_FLAGS_RECEPTION_TYPE_MASK) >> PACK_FLAGS_RECEPTION_TYPE_SHIFT)
#define PACK_FLAGS_RECEPTION_TYPE_UNSPECIFIED 0
#define PACK_FLAGS_RECEPTION_TYPE_UNICAST     1
#define PACK_FLAGS_RECEPTION_TYPE_MULTICAST   2
#define PACK_FLAGS_RECEPTION_TYPE_BROADCAST   3
#define PACK_FLAGS_RECEPTION_TYPE_PROMISCUOUS 4

/* FCS length field of the packet flags */
#define PACK_FLAGS_FCS_LENGTH_MASK                        0x000001E0 /* unshifted */
#define PACK_FLAGS_FCS_LENGTH_SHIFT                       5
#define PACK_FLAGS_FCS_LENGTH(pack_flags) (((pack_flags) & PACK_FLAGS_FCS_LENGTH_MASK) >> PACK_FLAGS_FCS_LENGTH_SHIFT)

/* Reserved bits of the packet flags */
#define PACK_FLAGS_RESERVED_MASK                          0x0000FE00

/* Link-layer-dependent errors of the packet flags */

/* For Ethernet and possibly some other network types */
#define PACK_FLAGS_CRC_ERROR                   0x01000000
#define PACK_FLAGS_PACKET_TOO_LONG             0x02000000
#define PACK_FLAGS_PACKET_TOO_SHORT            0x04000000
#define PACK_FLAGS_WRONG_INTER_FRAME_GAP       0x08000000
#define PACK_FLAGS_UNALIGNED_FRAME             0x10000000
#define PACK_FLAGS_START_FRAME_DELIMITER_ERROR 0x20000000
#define PACK_FLAGS_PREAMBLE_ERROR              0x40000000
#define PACK_FLAGS_SYMBOL_ERROR                0x80000000

/* Construct a pack_flags value from its subfield values */
#define PACK_FLAGS_VALUE(direction, reception_type, fcs_length, ll_dependent_errors) \
    (((direction) << 30) | \
    ((reception_type) << 27) | \
    ((fcs_length) << 23) | \
    (ll_dependent_errors))

/**
 * @brief Header metadata for a file-type-specific event or report record.
 */
typedef struct {
    int      file_type_subtype; /**< File type/subtype identifier for which this record is valid. */
    unsigned record_type;       /**< File-type-specific record subtype value (e.g. pcapng block type). */
    uint32_t record_len;        /**< Length of the record in bytes. */

    union wtap_pseudo_header pseudo_header; /**< Encapsulation-specific metadata associated with this record. */
} wtap_ft_specific_header;

/**
 * @brief Header metadata for a system call record (e.g. from Sysdig/Falco captures).
 */
typedef struct {
    const char *pathname;      /**< Path name of the source capture file. */
    unsigned    record_type;   /**< Record type; mirrors @c ft_specific_record_phdr for pcapng block chaining. */
    int         byte_order;    /**< Byte order of the record data (@c G_BIG_ENDIAN or @c G_LITTLE_ENDIAN). */
    uint64_t    timestamp;     /**< Event timestamp in nanoseconds since the Unix epoch. */
    uint64_t    thread_id;     /**< ID of the thread that generated the system call. */
    uint32_t    event_len;     /**< Total length of the ppm event in bytes. */
    uint32_t    event_data_len; /**< Length of the event payload (event_len minus the ppm event header length). */
    uint32_t    nparams;       /**< Number of parameters carried by this event. */
    uint32_t    flags;         /**< Event flags (ppm event flags). */
    uint16_t    event_type;    /**< ppm event type identifier. */
    uint16_t    cpu_id;        /**< ID of the CPU on which the event was captured. */
} wtap_syscall_header;

/**
 * @brief Header metadata for a systemd journal export record.
 */
typedef struct {
    uint32_t record_len; /**< Length of the journal export record in bytes. */
} wtap_systemd_journal_export_header;

/**
 * @brief Header metadata for a pcapng Custom Block record.
 */
typedef struct {
    uint32_t pen;          /**< IANA Private Enterprise Number identifying the block's owner. */
    uint32_t length;       /**< Length in bytes of the Custom Data field plus any options. */
    bool     copy_allowed; /**< True if this Custom Block may be copied to output files. */
} wtap_custom_block_header;

/*
 * The largest nstime.secs value that can be put into an unsigned
 * 32-bit quantity.
 *
 * We assume that time_t is signed; it is signed on Windows/MSVC and
 * on many UN*Xes.
 *
 * So, if time_t is 32-bit, we define this as INT32_MAX, as that's
 * the largest value a time_t can have, and it fits in an unsigned
 * 32-bit quantity.  If it's 64-bit or larger, we define this as
 * UINT32_MAX, as, even if it's signed, it can be as large as
 * UINT32_MAX, and that's the largest value that can fit in
 * a 32-bit unsigned quantity.
 *
 * Comparing against this, rather than against G_MAXINT2, when checking
 * whether a time stamp will fit in a 32-bit unsigned integer seconds
 * field in a capture file being written avoids signed vs. unsigned
 * warnings if time_t is a signed 32-bit type.
 *
 * XXX - what if time_t is unsigned?  Are there any platforms where
 * it is?
 */
#define WTAP_NSTIME_32BIT_SECS_MAX ((time_t)(sizeof(time_t) > sizeof(int32_t) ? UINT32_MAX : INT32_MAX))

/**
 * @brief Represents a single capture record read from or written to a capture file, regardless of record type.
 */
typedef struct wtap_rec {
    unsigned    rec_type;        /**< Record type identifier (e.g. REC_TYPE_PACKET, REC_TYPE_FT_SPECIFIC_EVENT). */
    uint32_t    presence_flags;  /**< Bitmask of WTAP_HAS_ flags indicating which optional fields are populated in this record. */
    unsigned    section_number;  /**< Zero-based index of the section within the capture file that contains this record. */
    nstime_t    ts;              /**< Timestamp at which this record was captured. */
    int         tsprec;          /**< Timestamp precision as a WTAP_TSPREC_ constant (e.g. WTAP_TSPREC_USEC, WTAP_TSPREC_NSEC). */
    const char *rec_type_name;   /**< Human-readable name of this record type, suitable for display and logging. */

    /**
     * @brief Type-specific record header, interpreted according to @ref rec_type.
     */
    union {
        wtap_packet_header                    packet_header;                /**< Header for standard captured network packets (REC_TYPE_PACKET). */
        wtap_ft_specific_header               ft_specific_header;           /**< Header for file-type-specific event records (REC_TYPE_FT_SPECIFIC_EVENT or REC_TYPE_FT_SPECIFIC_REPORT). */
        wtap_syscall_header                   syscall_header;               /**< Header for system call event records (REC_TYPE_SYSCALL). */
        wtap_systemd_journal_export_header    systemd_journal_export_header;/**< Header for systemd journal export records (REC_TYPE_SYSTEMD_JOURNAL_EXPORT). */
        wtap_custom_block_header              custom_block_header;          /**< Header for custom block records (REC_TYPE_CUSTOM_BLOCK). */
    } rec_header;

    /**
     * @brief Block-level metadata associated with this record.
     *
     * Carries structured block information (options, etc.) that may overlap with or
     * eventually supersede @ref rec_header. NULL for record types that do not
     * correspond to a pcapng block or equivalent construct.
     */
    wtap_block_t block;

    bool         block_was_modified; /**< True if any field or option within @ref block has been modified since it was read. */

    /**
     * @brief Reusable buffer holding serialized file-type-specific option data for this record.
     *
     * Using a persistent Buffer avoids per-record allocation and deallocation overhead for option payloads.
     */
    Buffer       options_buf;

    Buffer       data; /**< Raw bytes of the record payload (e.g. the captured packet data). */
} wtap_rec;

/*
 * Bits in presence_flags, indicating which of the fields we have.
 *
 * For the time stamp, we may need some more flags to indicate
 * whether the time stamp is an absolute date-and-time stamp, an
 * absolute time-only stamp (which can make relative time
 * calculations tricky, as you could in theory have two time
 * stamps separated by an unknown number of days), or a time stamp
 * relative to some unspecified time in the past (see mpeg.c).
 *
 * There is no presence flag for len - there has to be *some* length
 * value for the packet.  (The "captured length" can be missing if
 * the file format doesn't report a captured length distinct from
 * the on-the-network length because the application(s) producing those
 * files don't support slicing packets.)
 *
 * There could be a presence flag for the packet encapsulation - if it's
 * absent, use the file encapsulation - but it's not clear that's useful;
 * we currently do that in the module for the file format.
 *
 * Only WTAP_HAS_TS and WTAP_HAS_SECTION_NUMBER apply to all record types.
 */
#define WTAP_HAS_TS             0x00000001  /**< time stamp */
#define WTAP_HAS_CAP_LEN        0x00000002  /**< captured length separate from on-the-network length */
#define WTAP_HAS_INTERFACE_ID   0x00000004  /**< interface ID */
#define WTAP_HAS_SECTION_NUMBER 0x00000008  /**< section number */

/*
 * The old max name length define, both for backwards compatibility and because
 * other name types (in epan) use it. While Name Resolution Blocks (NRBs) only
 * support IPv4 and IPv6 currently, they could later support other name types.
 */
#ifndef MAXNAMELEN
#define MAXNAMELEN  	64	/* max name length (most names: DNS labels, services, eth) */
#endif

#ifndef MAXDNSNAMELEN
#define MAXDNSNAMELEN  	256	/* max total length of a domain name in DNS */
#endif

/**
 * @brief Hash table entry for a resolved or unresolved IPv4 address.
 */
typedef struct hashipv4 {
    unsigned addr;                          /**< IPv4 address in host byte order used as the hash key. */
    uint8_t  flags;                         /**< State flags: B0 = dummy entry, B1 = resolution attempted, B2 = address appears in the capture. */
    char     ip[WS_INET_ADDRSTRLEN];        /**< Dotted-decimal string representation of the IPv4 address (e.g. "192.168.1.1"). */
    char     name[MAXDNSNAMELEN];           /**< Resolved DNS hostname for this address, or an empty string if unresolved. */
    char     cidr_addr[WS_INET_CIDRADDRSTRLEN]; /**< CIDR notation string representation of the IPv4 address/prefix (e.g. "192.168.1.0/24"). */
} hashipv4_t;


/**
 * @brief Hash table entry for a resolved or unresolved IPv6 address.
 */
typedef struct hashipv6 {
    uint8_t addr[16];                           /**< IPv6 address in network byte order used as the hash key. */
    uint8_t flags;                              /**< State flags: B0 = dummy entry, B1 = resolution attempted, B2 = address appears in the capture. */
    char    ip6[WS_INET6_ADDRSTRLEN];           /**< Colon-separated string representation of the IPv6 address (e.g. "2001:db8::1"). */
    char    name[MAXDNSNAMELEN];                /**< Resolved DNS hostname for this address, or an empty string if unresolved. */
    char    cidr_addr[WS_INET6_CIDRADDRSTRLEN]; /**< CIDR notation string representation of the IPv6 address/prefix (e.g. "2001:db8::/32"). */
} hashipv6_t;


/**
 * @brief Aggregates lists of resolved IPv4 and IPv6 addresses for writing into a pcapng Name Resolution Block (NRB).
 */
typedef struct addrinfo_lists {
    GList *ipv4_addr_list; /**< A list of resolved hashipv4_t entries to be written into the NRB. */
    GList *ipv6_addr_list; /**< A list of resolved hashipv6_t entries to be written into the NRB. */
} addrinfo_lists_t;

/**
 * Parameters for various wtap_dump_* functions, specifying per-file
 * information. The structure itself is no longer used after returning
 * from wtap_dump_*, but its pointer fields must remain valid until
 * wtap_dump_close is called.
 *
 * @note The shb_hdr and idb_inf arguments will be used until
 *     wtap_dump_close() is called, but will not be free'd by the dumper. If
 *     you created them, you must free them yourself after wtap_dump_close().
 *     dsbs_initial will be unreferenced by wtap_dump_close(), so to reuse
 *     them for another dump file, call wtap_block_array_ref() before closing.
 *     dsbs_growing typically refers to another wth->dsbs.
 *     nrbs_growing typically refers to another wth->nrbs.
 *
 * @see wtap_dump_params_init, wtap_dump_params_cleanup.
 */
typedef struct wtap_dump_params {
    int         encap;                      /**< Per-file packet encapsulation, or WTAP_ENCAP_PER_PACKET */
    int         snaplen;                    /**< Per-file snapshot length (what if it's per-interface?) */
    int         tsprec;                     /**< Per-file time stamp precision */
    GArray     *shb_hdrs;                   /**< The section header block(s) information, or NULL. */
    const GArray *shb_iface_to_global;      /**< An array mapping the per-section interface numbers to global IDs
                                                 This array may grow after the dumper is opened if a new
                                                 section header is read. */
    wtapng_iface_descriptions_t *idb_inf;   /**< The interface description information, or NULL. */
    const GArray *nrbs_growing;             /**< NRBs that will be written while writing packets, or NULL.
                                                 This array may grow since the dumper was opened and will subsequently
                                                 be written before newer packets are written in wtap_dump. */
    GArray     *dsbs_initial;               /**< The initial Decryption Secrets Block(s) to be written, or NULL. */
    const GArray *dsbs_growing;             /**< DSBs that will be written while writing packets, or NULL.
                                                 This array may grow since the dumper was opened and will subsequently
                                                 be written before newer packets are written in wtap_dump. */
    const GArray *mevs_growing;             /**< Meta events that will be written while writing packets, or NULL.
                                                 This array may grow since the dumper was opened and will subsequently
                                                 be written before newer packets are written in wtap_dump. */
    const GArray *dpibs_growing;            /**< DPIBs that will be written while writing packets, or NULL.
                                                 This array may grow since the dumper was opened and will subsequently
                                                 be written before newer packets are written in wtap_dump. */
    bool        dont_copy_idbs;             /**< XXX - don't copy IDBs; this should eventually always be the case. */
} wtap_dump_params;

/* Zero-initializer for wtap_dump_params. */
#define WTAP_DUMP_PARAMS_INIT {.snaplen=0}

struct wtap_dumper;

typedef struct wtap wtap;
typedef struct wtap_dumper wtap_dumper;

typedef struct wtap_reader *FILE_T;

/**
 * @brief Companion metadata block for Lua-based file writers registered via wslua, carrying the write-open callback reference and its associated state.
 *
 * Similar to the wtap_open_routine_info for open routines, the following
 * wtap_wslua_file_info struct is used by wslua code for Lua-based file writers.
 *
 * This concept is necessary because when wslua goes to invoke the
 * registered dump/write_open routine callback in Lua, it needs the ref number representing
 * the hooked function inside Lua.  This will be stored in the thing pointed to
 * by the void* data here.  This 'data' pointer will be copied into the
 * wtap_dumper struct's 'void* data' member when calling the dump_open function,
 * which is how wslua finally retrieves it.  Unlike wtap_dumper's 'priv' member, its
 * 'data' member is not free'd in wtap_dump_close().
 */
typedef struct wtap_wslua_file_info {
    int (*wslua_can_write_encap)(int, void*); /**< Callback that returns non-zero if the Lua writer supports the given WTAP_ENCAP_ encapsulation type; the void* receives @ref wslua_data. */
    void *wslua_data;                         /**< Opaque pointer to the Lua state or ref data needed by wslua when invoking the registered write-open and dump callbacks. */
} wtap_wslua_file_info_t;

/**
 * @brief For registering extensions used for file formats.
 *
 * These items are used in dialogs for opening files, so that
 * the user can ask to see all capture files (as identified
 * by file extension) or particular types of capture files.
 *
 * Each item has a human-readable description of the file types
 * (possibly more than one!) that use all of this set of extensions,
 * a flag indicating whether it's a capture file or just some file
 * whose contents we can dissect, and a list of extensions files of
 * that type might have.
 *
 * Note that entries in this table do *not* necessarily correspond
 * to single file types; for example, the entry that lists just "cap"
 * is for several file formats, all of which use the extension ".cap".
 *
 * Also note that a given extension may appear in multiple entries;
 * for example, "cap" (again!) is in an entry for some file types
 * that use only ".cap" and in entries for file types that use
 * ".cap" and some other extensions, and ".trc" is used both for
 * DOS Sniffer Token Ring captures ("trc") and EyeSDN USB ISDN
 * trace files ("tr{a}c{e}").
 *
 * Some entries aren't for capture file types, they're just generic types,
 * such as "text file" or "XML file", that can be used for, among other
 * things, captures we can read, or for file formats we can read in
 * order to dissect the contents of the file (think of this as "Fileshark",
 * which is a program that we really should have).  Those are marked
 * specially, because, in file section dialogs, the user should be able
 * to select "All Capture Files" and get a set of extensions that are
 * associated with capture file formats, but not with files in other
 * formats that might or might not contain captured packets (such as
 * .txt or .xml") or formats that aren't capture files but that we
 * support as "we're being Fileshark now" (such as .jpeg).  The routine
 * that constructs a list of extensions for "All Capture Files" omits
 * extensions for those entries.
 */
struct file_extension_info {
    const char *name;       /**< Human-readable description of the file type. */
    bool is_capture_file;   /**< True if this is a capture file format. */
    const char *extensions; /**< Semicolon-separated list of file extensions. */
};

/**
 * @brief For registering file types that we can open.
 *
 * Each file type has an open routine.
 *
 * The open routine should return:
 *
 *      WTAP_OPEN_ERROR on an I/O error;
 *
 *      WTAP_OPEN_MINE if the file it's reading is one of the types
 *      it handles;
 *
 *      WTAP_OPEN_NOT_MINE if the file it's reading isn't one of the
 *      types it handles.
 *
 * If the routine handles this type of file, it should set the
 * "file_type_subtype" field in the "struct wtap" to the type of the file.
 *
 * Note that the routine does not have to free the private data pointer on
 * error. The caller takes care of that by calling wtap_close on error.
 * (See https://gitlab.com/wireshark/wireshark/-/issues/8518)
 *
 * However, the caller does have to free the private data pointer when
 * returning WTAP_OPEN_NOT_MINE, since the next file type will be called
 * and will likely just overwrite the pointer.
 */
typedef enum {
    WTAP_OPEN_NOT_MINE = 0, /**< File isn't handled by this module. */
    WTAP_OPEN_MINE = 1,     /**< File is handled by this module. */
    WTAP_OPEN_ERROR = -1    /**< I/O error occurred while opening the file. */
} wtap_open_return_val;

typedef wtap_open_return_val (*wtap_open_routine_t)(struct wtap*, int *,
    char **);

/**
 * @brief Strategy used to identify a file format.
 *
 * Some file formats have defined magic numbers at fixed offsets from
 * the beginning of the file; those routines should return 1 if and
 * only if the file has the magic number at that offset.  (pcapng
 * is a bit of a special case, as it has both the Section Header Block
 * type field and its byte-order magic field; it checks for both.)
 * Those file formats do not require a file name extension in order
 * to recognize them or to avoid recognizing other file types as that
 * type, and have no extensions specified for them.
 *
 * Other file formats don't have defined magic numbers at fixed offsets,
 * so a heuristic is required.  If that file format has any file name
 * extensions used for it, a list of those extensions should be
 * specified, so that, if the name of the file being opened has an
 * extension, the file formats that use that extension are tried before
 * the ones that don't, to handle the case where a file of one type
 * might be recognized by the heuristics for a different file type.
 */
typedef enum {
    OPEN_INFO_MAGIC = 0,    /**< Format identified by a fixed magic number at a known offset. */
    OPEN_INFO_HEURISTIC = 1 /**< Format identified by heuristic inspection of file contents. */
} wtap_open_type;

/**
 * @brief Initialize registered file open routines.
 *
 * Registers a set of default file open handlers for wiretap modules.
 * Typically called during initialization or module loading.
 */
WS_DLL_PUBLIC void init_open_routines(void);

/**
 * @brief Clean up registered file open routines.
 *
 * Frees any resources or state associated with wiretap module open handlers.
 * Typically called during shutdown or module unloading.
 */
void cleanup_open_routines(void);

/**
 * @brief Information about a given file type that applies to all subtypes of
 * the file type.
 *
 * Each file type has:
 *
 *    a human-readable description of the file type, for use in the
 *      user interface;
 *    a wtap_open_type indication of how the open routine
 *      determines whether a file is of that type;
 *    an open routine;
 *    an optional list of extensions used for this file type;
 *    data to be passed to Lua file readers - this should be NULL for
 *      non-Lua (C) file readers.
 *
 * The list of file extensions is used as a hint when calling open routines
 * to open a file; heuristic open routines whose list of extensions includes
 * the file's extension are called before heuristic open routines whose
 * (possibly-empty) list of extensions doesn't contain the file's extension,
 * to reduce the chances that a file will be misidentified due to an heuristic
 * test with a weak heuristic being done before a heuristic test for the
 * file's type.
 *
 * The list of extensions should be NULL for magic-number open routines,
 * as it will not be used for any purpose (no such hinting is done).
 */
struct open_info {
    const char *name;                 /**< Description */
    wtap_open_type type;              /**< Open routine type */
    wtap_open_routine_t open_routine; /**< Open routine */
    const char *extensions;           /**< List of extensions used for this file type */
    char **extensions_set;            /**< Array of those extensions; populated using extensions member during initialization */
    void* wslua_data;                 /**< Data for Lua file readers */
};

/**
 * @brief Table of registered wiretap file open handlers.
 *
 * Each entry describes how to recognize and open a supported file format.
 * Populated during wiretap module initialization.
 */
WS_DLL_PUBLIC struct open_info *open_routines;

/*
 * Types of comments.
 */
 /**
 * @brief Comment applies to the entire file or file section.
 *
 * Used for global annotations such as capture metadata or session notes.
 */
#define WTAP_COMMENT_PER_SECTION        0x00000001      /* per-file/per-file-section */

/**
 * @brief Comment applies to a specific interface.
 *
 * Useful for describing interface-specific settings or observations.
 */
#define WTAP_COMMENT_PER_INTERFACE      0x00000002      /* per-interface */

/**
 * @brief Comment applies to an individual packet.
 *
 * Enables fine-grained annotations such as decoding notes or anomalies.
 */
#define WTAP_COMMENT_PER_PACKET         0x00000004      /* per-packet */

/**
 * @brief Indicates how a file format supports a given option type.
 *
 * Used to describe whether a block type can include zero, one, or multiple instances
 * of a specific option type.
 *
 * For a given option type in a certain block type, does a file format
 * not support it, support only one such option, or support multiple
 * such options?
 */
typedef enum {
    OPTION_NOT_SUPPORTED,      /**< The option type is not supported in this block. */
    ONE_OPTION_SUPPORTED,      /**< Only one instance of the option type is supported. */
    MULTIPLE_OPTIONS_SUPPORTED /**< Multiple instances of the option type are supported. */
} option_support_t;

/**
 * @brief Entry describing support level for a specific option type.
 *
 * Indicates whether a block type supports zero, one, or multiple instances
 * of a given option. Used in format capability tables.
 */
struct supported_option_type {
    unsigned opt;                  /**< Option type identifier. */
    option_support_t support;     /**< Support level for this option type. */
};

/**
 * @brief Declare supported option types for a block.
 *
 * Expands to the length of the option type array and the array itself.
 */
#define OPTION_TYPES_SUPPORTED(option_type_array) \
    array_length(option_type_array), option_type_array

/**
 * @brief Declare that no option types are supported for a block.
 *
 * Expands to zero and NULL, indicating absence of supported options.
 */
#define NO_OPTIONS_SUPPORTED \
    0, NULL

/**
 * @brief Indicates how many instances of a given block type a file format supports.
 */
typedef enum {
    BLOCK_NOT_SUPPORTED,       /**< The file format does not support this block type at all */
    ONE_BLOCK_SUPPORTED,       /**< The file format supports exactly one instance of this block type */
    MULTIPLE_BLOCKS_SUPPORTED  /**< The file format supports multiple instances of this block type */
} block_support_t;

/**
 * @brief Describes a single block type supported by a file format, including its option support.
 */
struct supported_block_type {
    wtap_block_type_t              type;                  /**< The block type this entry describes (see ::wtap_block_type_t) */
    block_support_t                support;               /**< Number of instances the format allows; ::BLOCK_NOT_SUPPORTED is equivalent to omitting the entry */
    size_t                         num_supported_options; /**< Number of entries in the @p supported_options array */
    const struct supported_option_type *supported_options;/**< Array of option types supported within this block type, or NULL if none */
};

#define BLOCKS_SUPPORTED(block_type_array) \
    array_length(block_type_array), block_type_array

/**
 * @brief Describes a single capture file type/subtype, including its metadata, capability flags, and I/O function pointers.
*/
struct file_type_subtype_info {
    /**
     * The file type description.
     */
    const char *description;

    /**
     * The file type name, used to look up file types by name, e.g.
     * looking up a file type specified as a command-line argument.
     */
    const char *name;

    /**
     * The default file extension, used to save this type.
     * Should be NULL if no default extension is known.
     */
    const char *default_file_extension;

    /**
     * A semicolon-separated list of additional file extensions
     * used for this type.
     * Should be NULL if no extensions, or no extensions other
     * than the default extension, are known.
     */
    const char *additional_file_extensions;

    /**
     * When writing this file format, is seeking required?
     */
    bool writing_must_seek;

    /**
     * Number of block types supported.
     */
    size_t num_supported_blocks;

    /**
     * Table of block types supported.
     */
    const struct supported_block_type *supported_blocks;

    /**
     * Can this type write this encapsulation format?
     * Should be NULL is this file type doesn't have write support.
     *
     * XXX - This returns an int because it can return err codes,
     * specifically WTAP_ERR_CHECK_WSLUA (instead of having an
     * int *err parameter like the other functions.)
     */
    int (*can_write_encap)(int);

    /**
     * The function to open the capture file for writing.
     * Should be NULL if this file type doesn't have write support.
     */
    bool (*dump_open)(wtap_dumper *, int *, char **);

    /**
     * If can_write_encap returned WTAP_ERR_CHECK_WSLUA, then this is used instead.
     * This should be NULL for everyone except Lua-based file writers.
     */
    wtap_wslua_file_info_t *wslua_info;
};

#define WTAP_TYPE_AUTO 0

/**
 * @brief Initialize the Wiretap library.
 *
 * @param load_wiretap_plugins Load Wiretap plugins when initializing library.
 * @param app_env_var_prefix The prefix for the application environment variable used to get the personal config directory.
 * @param file_extensions Array of file extensions supported by the application
 * @param num_extensions Number of file extensions supported by the application
*/
WS_DLL_PUBLIC
void wtap_init(bool load_wiretap_plugins, const char* app_env_var_prefix, const struct file_extension_info* file_extensions, unsigned num_extensions);

/**
 * @brief Open a capture file for offline analysis.
 *
 * Attempts to open the specified file using either automatic format detection
 * or an explicitly chosen format. On failure, returns NULL and stores error details
 * into the "int" pointed to by its second argument:
 *
 * @param filename Name of the file to open
 * @param type WTAP_TYPE_AUTO for automatic recognize file format or explicit choose format type
 * @param[out] err a positive "errno" value if the capture file can't be opened;
 * a negative number, indicating the type of error, on other failures.
 * @param[out] err_info for some errors, a string giving more details of
 * the error
 * @param do_random true if random access to the file will be done,
 * @param app_env_var_prefix The prefix for the application environment variable used to get the personal config directory.
 * false if not
 */
WS_DLL_PUBLIC
struct wtap* wtap_open_offline(const char *filename, unsigned int type, int *err,
    char **err_info, bool do_random, const char* app_env_var_prefix);

/**
 * @brief Clear EOF status for a wiretap file.
 *
 * If compiled with zlib and the file is at EOF, this resets the EOF flag
 * to allow continued reading. Useful when tailing a file that may grow.
 *
 * @param wth Wiretap file handle.
 */
WS_DLL_PUBLIC
void wtap_cleareof(wtap *wth);

/**
 * @brief Callback type for registering new IPv4 hostnames.
 *
 * Used to associate an IPv4 address with a hostname during file parsing.
 * Must match the signature of add_ipv4_name in addr_resolv.c.
 *
 * @param addr IPv4 address in host byte order.
 * @param name Hostname to associate.
 * @param static_entry True if the entry is static; false if dynamic.
 */
typedef void (*wtap_new_ipv4_callback_t) (const unsigned addr, const char *name, const bool static_entry);

/**
 * @brief Set the callback for adding new IPv4 hostnames.
 *
 * Registers a function to be called when new IPv4 addresses are discovered.
 * Currently used only for pcapng files.
 *
 * @param wth Wiretap file handle.
 * @param add_new_ipv4 Callback function to register.
 */
WS_DLL_PUBLIC
void wtap_set_cb_new_ipv4(wtap *wth, wtap_new_ipv4_callback_t add_new_ipv4);

/**
 * @brief Callback type for registering new IPv6 hostnames.
 *
 * Used to associate an IPv6 address with a hostname during file parsing.
 * Must match the signature of add_ipv6_name in addr_resolv.c.
 *
 * @param addrp Pointer to IPv6 address.
 * @param name Hostname to associate.
 * @param static_entry True if the entry is static; false if dynamic.
 */
typedef void (*wtap_new_ipv6_callback_t) (const ws_in6_addr *addrp, const char *name, const bool static_entry);

/**
 * @brief Set the callback for adding new IPv6 hostnames.
 *
 * Registers a function to be called when new IPv6 addresses are discovered.
 * Currently used only for pcapng files.
 *
 * @param wth Wiretap file handle.
 * @param add_new_ipv6 Callback function to register.
 */
WS_DLL_PUBLIC
void wtap_set_cb_new_ipv6(wtap *wth, wtap_new_ipv6_callback_t add_new_ipv6);

/**
 * @brief Callback type for receiving new decryption secrets.
 *
 * Used to register secrets (e.g., TLS keys) discovered during file parsing.
 * The secrets type is defined in secrets-types.h. Currently used only for pcapng.
 *
 * @param secrets_type Type identifier for the secrets.
 * @param secrets Pointer to the secrets data.
 * @param size Size of the secrets data in bytes.
 */
typedef void (*wtap_new_secrets_callback_t)(uint32_t secrets_type, const void *secrets, unsigned size);

/**
 * @brief Set the callback for receiving new decryption secrets.
 *
 * Registers a function to be called when decryption secrets are discovered.
 * Currently used only for pcapng files.
 *
 * @param wth Wiretap file handle.
 * @param add_new_secrets Callback function to register.
 */
WS_DLL_PUBLIC
void wtap_set_cb_new_secrets(wtap *wth, wtap_new_secrets_callback_t add_new_secrets);

/**
 * @brief Read the next record in the file, filling in *phdr and *buf.
 *
 * @param wth a wtap * returned by a call that opened a file for reading.
 * @param rec a pointer to a wtap_rec, filled in with information about the
 * record and the data from the record.
 * @param err a positive "errno" value, or a negative number indicating
 * the type of error, if the read failed.
 * @param err_info for some errors, a string giving more details of
 * the error
 * @param offset a pointer to a int64_t, set to the offset in the file
 * that should be used on calls to wtap_seek_read() to reread that record,
 * if the read succeeded.
 * @return true on success, false on failure.
 */
WS_DLL_PUBLIC
bool wtap_read(wtap *wth, wtap_rec *rec, int *err, char **err_info,
    int64_t *offset);

/**
 * @brief Read the record at a specified offset in a capture file, filling in
 * *phdr and *buf.
 *
 * @param wth a wtap * returned by a call that opened a file for random-access
 * reading.
 * @param seek_off a int64_t giving an offset value returned by a previous
 * wtap_read() call.
 * @param rec a pointer to a struct wtap_rec, filled in with information
 * about the record and the data from the record.
 * @param err a positive "errno" value, or a negative number indicating
 * the type of error, if the read failed.
 * @param err_info for some errors, a string giving more details of
 * the error
 * @return true on success, false on failure.
 */
WS_DLL_PUBLIC
bool wtap_seek_read(wtap *wth, int64_t seek_off, wtap_rec *rec,
    int *err, char **err_info);

/**
 * @brief Initialize a wtap_rec structure.
 *
 * Allocates internal space and prepares the record for use.
 *
 * @param rec Pointer to the wtap_rec structure.
 * @param space Size of internal allocation.
 */
WS_DLL_PUBLIC
void wtap_rec_init(wtap_rec *rec, size_t space);

/**
 * @brief Apply a snapshot length to a wtap_rec.
 *
 * Sets the maximum captured packet length for the record.
 *
 * @param rec Pointer to the wtap_rec structure.
 * @param snaplen Snapshot length in bytes.
 */
WS_DLL_PUBLIC
void wtap_rec_apply_snapshot(wtap_rec *rec, uint32_t snaplen);

/**
 * @brief Re-initialize a wtap_rec structure.
 *
 * Clears existing content and resets the record for reuse.
 *
 * @param rec Pointer to the wtap_rec structure.
 */
WS_DLL_PUBLIC
void wtap_rec_reset(wtap_rec *rec);

/**
 * @brief Clean up a wtap_rec structure.
 *
 * Frees any memory allocated by wtap_rec_init().
 *
 * @param rec Pointer to the wtap_rec structure.
 */
WS_DLL_PUBLIC
void wtap_rec_cleanup(wtap_rec *rec);

/**
 * @brief Return an error string for WTAP_ERR_UNWRITABLE_REC_TYPE.
 *
 * Provides a human-readable explanation for why a given record type
 * cannot be written to a file.
 *
 * @param rec Pointer to the wtap_rec structure.
 * @return Error string describing the issue.
 */
WS_DLL_PUBLIC
char *wtap_unwritable_rec_type_err_string(const wtap_rec *rec);

/**
 * @brief Set up a wtap_rec for a packet (REC_TYPE_PACKET).
 *
 * Initializes the record type and encapsulation for a packet record.
 *
 * @param rec Pointer to the wtap_rec structure.
 * @param encap Encapsulation type (WTAP_ENCAP_...).
 */
WS_DLL_PUBLIC
void wtap_setup_packet_rec(wtap_rec *rec, int encap);

/**
 * @brief Set up a wtap_rec for a file-type specific event.
 *
 * Initializes the record as REC_TYPE_FT_SPECIFIC_EVENT with the given subtype and record type.
 *
 * @param rec Pointer to the wtap_rec structure.
 * @param file_type_subtype Format-specific subtype identifier.
 * @param record_type Format-specific record type identifier.
 */
WS_DLL_PUBLIC
void wtap_setup_ft_specific_event_rec(wtap_rec *rec, int file_type_subtype,
                                      unsigned record_type);

/**
 * @brief Set up a wtap_rec for a file-type specific report.
 *
 * Initializes the record as REC_TYPE_FT_SPECIFIC_REPORT with the given subtype and record type.
 *
 * @param rec Pointer to the wtap_rec structure.
 * @param file_type_subtype Format-specific subtype identifier.
 * @param record_type Format-specific record type identifier.
 */
WS_DLL_PUBLIC
void wtap_setup_ft_specific_report_rec(wtap_rec *rec, int file_type_subtype,
                                       unsigned record_type);

/**
 * @brief Set up a wtap_rec for a system call.
 *
 * Initializes the record as REC_TYPE_SYSCALL for syscall trace data.
 *
 * @param rec Pointer to the wtap_rec structure.
 */
WS_DLL_PUBLIC
void wtap_setup_syscall_rec(wtap_rec *rec);

/**
 * @brief Set up a wtap_rec for a systemd journal export entry.
 *
 * Initializes the record as REC_TYPE_SYSTEMD_JOURNAL_EXPORT for journal export data.
 *
 * @param rec Pointer to the wtap_rec structure.
 */
WS_DLL_PUBLIC
void wtap_setup_systemd_journal_export_rec(wtap_rec *rec);

/**
 * @brief Set up a wtap_rec for a custom block.
 *
 * Initializes the record as REC_TYPE_CUSTOM_BLOCK with the given Private Enterprise Number (PEN),
 * payload length, and copy permission flag.
 *
 * @param rec Pointer to the wtap_rec structure.
 * @param pen Private Enterprise Number identifying the block owner.
 * @param payload_length Length of the custom block payload in bytes.
 * @param copy_allowed True if copying the block is permitted; false otherwise.
 */
WS_DLL_PUBLIC
void wtap_setup_custom_block_rec(wtap_rec *rec, uint32_t pen,
                                 uint32_t payload_length, bool copy_allowed);

/**
 * @brief Get the compression type used for the capture file.
 *
 * Returns the compression method applied to the file, if any.
 *
 * @param wth Wiretap file handle.
 * @return Compression type (e.g., none, gzip).
 */
WS_DLL_PUBLIC
ws_compression_type wtap_get_compression_type(wtap *wth);

/*** get various information snippets about the current file ***/

/**
 * @brief Return an approximation of the amount of data read sequentially.
 *
 * Provides a rough estimate of how many bytes have been read from the file so far,
 * useful for progress tracking or tailing scenarios.
 *
 * @param wth Wiretap file handle.
 * @return Number of bytes read sequentially.
 */
WS_DLL_PUBLIC
int64_t wtap_read_so_far(wtap *wth);

/**
 * @brief Get the size of the capture file.
 *
 * Returns the total file size in bytes. On failure, sets an error code.
 *
 * @param wth Wiretap file handle.
 * @param err Pointer to an error code variable.
 * @return File size in bytes, or -1 on error.
 */
WS_DLL_PUBLIC
int64_t wtap_file_size(wtap *wth, int *err);

/**
 * @brief Get the snapshot length for the capture file.
 *
 * Returns the maximum number of bytes captured per packet.
 *
 * @param wth Wiretap file handle.
 * @return Snapshot length in bytes.
 */
WS_DLL_PUBLIC
unsigned wtap_snapshot_length(wtap *wth);

/**
 * @brief Get the file type subtype.
 *
 * Returns the format-specific subtype identifier for the capture file.
 *
 * @param wth Wiretap file handle.
 * @return File type subtype.
 */
WS_DLL_PUBLIC
int wtap_file_type_subtype(wtap *wth);

/**
 * @brief Get the encapsulation type for the capture file.
 *
 * Returns the WTAP_ENCAP_... value used for packet encapsulation.
 *
 * @param wth Wiretap file handle.
 * @return Encapsulation type.
 */
WS_DLL_PUBLIC
int wtap_file_encap(wtap *wth);

/**
 * @brief Get the timestamp precision for the capture file.
 *
 * Returns the WTAP_TSPREC_... value indicating timestamp resolution.
 *
 * @param wth Wiretap file handle.
 * @return Timestamp precision.
 */
WS_DLL_PUBLIC
int wtap_file_tsprec(wtap *wth);

/**
 * @brief Get the start timestamp of the capture file.
 *
 * Returns a pointer to the first packet's timestamp, if available.
 *
 * @param wth Wiretap file handle.
 * @return Pointer to start timestamp, or NULL if unavailable.
 */
WS_DLL_PUBLIC
const nstime_t* wtap_file_start_ts(wtap *wth);

/**
 * @brief Get the end timestamp of the capture file.
 *
 * Returns a pointer to the last packet's timestamp, if available.
 *
 * @param wth Wiretap file handle.
 * @return Pointer to end timestamp, or NULL if unavailable.
 */
WS_DLL_PUBLIC
const nstime_t* wtap_file_end_ts(wtap *wth);

/**
 * @brief Gets number of section header blocks.
 * @details Returns the number of existing SHBs.
 *
 * @param wth The wiretap session.
 * @return The number of existing section headers.
 */
WS_DLL_PUBLIC
unsigned wtap_file_get_num_shbs(wtap *wth);

/**
 * @brief Gets existing section header block, not for new file.
 * @details Returns the pointer to an existing SHB, without creating a
 *          new one. This should only be used for accessing info, not
 *          for creating a new file based on existing SHB info. Use
 *          wtap_file_get_shb_for_new_file() for that.
 *
 * @param wth The wiretap session.
 * @param shb_num The ordinal number (0-based) of the section header
 * in the file
 * @return The specified existing section header, which must NOT be g_free'd.
 */
WS_DLL_PUBLIC
wtap_block_t wtap_file_get_shb(wtap *wth, unsigned shb_num);

/**
 * @brief Sets or replaces the section header comment.
 * @details The passed-in comment string is set to be the comment
 *          for the section header block. The passed-in string's
 *          ownership will be owned by the block, so it should be
 *          duplicated before passing into this function.
 *
 * @param wth The wiretap session.
 * @param comment The comment string.
 */
WS_DLL_PUBLIC
void wtap_write_shb_comment(wtap *wth, char *comment);

/**
 * @brief Gets the unique interface id for a SHB's interface
 * @details Given an existing SHB number and an interface ID within
 *          that section, returns the unique ordinal number (0-based)
 *          of that interface over the entire wiretap session.
 *
 * @param wth The wiretap session.
 * @param shb_num The ordinal number (0-based) of a section header
 * @param interface_id An interface id within the section
 * @return The unique wtap session-wide interface id for that interface
 */
WS_DLL_PUBLIC
unsigned wtap_file_get_shb_global_interface_id(wtap *wth, unsigned shb_num, uint32_t interface_id);

/**
 * @brief Gets existing interface descriptions.
 * @details Returns a new struct containing a pointer to the existing
 *          description, without creating new descriptions internally.
 * @note The returned pointer must be g_free'd, but its internal
 *       interface_data must not.
 *
 * @param wth The wiretap session.
 * @return A new struct of the existing section descriptions, which must be g_free'd.
 */
WS_DLL_PUBLIC
wtapng_iface_descriptions_t *wtap_file_get_idb_info(wtap *wth);


/**
 * @brief Gets the DPIB lookup information for the current file.
 *
 * @param wth The wiretap session.
 * @return Pointer to the existing DPIB lookup information, or NULL if none available.
 */
WS_DLL_PUBLIC
wtapng_dpib_lookup_info_t * wtap_file_get_dpib_lookup_info(wtap *wth);

/**
 * @brief Gets next interface description.
 *
 * @details This returns the first unfetched wtap_block_t from the set
 * of interface descriptions.  Returns NULL if there are no more
 * unfetched interface descriptions; a subsequent call after
 * wtap_read() returns, either with a new record or an EOF, may return
 * another interface description.
 */
WS_DLL_PUBLIC
wtap_block_t wtap_get_next_interface_description(wtap *wth);

/**
 * @brief Free's a interface description block and all of its members.
 *
 * @details This free's all of the interface descriptions inside the passed-in
 *     struct, including their members (e.g., comments); and then free's the
 *     passed-in struct as well.
 *
 * @warning Do not use this for the struct returned by
 *     wtap_file_get_idb_info(), as that one did not create the internal
 *     interface descriptions; for that case you can simply g_free() the new
 *     struct.
 */
WS_DLL_PUBLIC
void wtap_free_idb_info(wtapng_iface_descriptions_t *idb_info);

/**
 * @brief Gets a debug string of an interface description.
 * @details Returns a newly allocated string of debug information about
 *          the given interface description, useful for debugging.
 * @note The returned pointer must be g_free'd.
 *
 * @param if_descr The interface description.
 * @param indent Number of spaces to indent each line by.
 * @param line_end A string to append to each line (e.g., "\n" or ", ").
 * @return A newly allocated gcahr array string, which must be g_free'd.
 */
WS_DLL_PUBLIC
char *wtap_get_debug_if_descr(const wtap_block_t if_descr,
                               const int indent,
                               const char* line_end);

/**
 * @brief Gets existing name resolution block, not for new file.
 * @details Returns the pointer to the existing NRB, without creating a
 *          new one. This should only be used for accessing info, not
 *          for creating a new file based on existing NRB info. Use
 *          wtap_file_get_nrb_for_new_file() for that.
 *
 * @param wth The wiretap session.
 * @return The existing section header, which must NOT be g_free'd.
 *
 * XXX - need to be updated to handle multiple NRBs.
 */
WS_DLL_PUBLIC
wtap_block_t wtap_file_get_nrb(wtap *wth);

/**
 * @brief Gets number of decryption secrets blocks.
 * @details Returns the number of existing DSBs.
 *
 * @param wth The wiretap session.
 * @return The number of existing decryption secrets blocks.
 */
WS_DLL_PUBLIC
unsigned wtap_file_get_num_dsbs(wtap *wth);

/**
 * @brief Gets existing decryption secrets block, not for new file.
 * @details Returns the pointer to an existing DSB, without creating a
 *          new one. This should only be used for accessing info.
 *
 * @param wth The wiretap session.
 * @param dsb_num The ordinal number (0-based) of the decryption secrets block
 * in the file
 * @return The specified existing decryption secrets block, which must NOT be g_free'd.
 */
WS_DLL_PUBLIC
wtap_block_t wtap_file_get_dsb(wtap *wth, unsigned dsb_num);

/**
 * @brief Adds a Decryption Secrets Block to the open wiretap session.
 * @details The passed-in DSB is added to the DSBs for the current
 *          session.
 *
 * @param wth The wiretap session.
 * @param dsb The Decryption Secrets Block to add
 */
WS_DLL_PUBLIC
void wtap_file_add_decryption_secrets(wtap *wth, const wtap_block_t dsb);

/**
 * @brief Remove any decryption secret information from the per-file information;
 * used if we're stripping decryption secrets while the file is open.
 *
 * @param wth The wiretap session from which to remove the
 * decryption secrets.
 * @return true if any DSBs were removed
 */
WS_DLL_PUBLIC
bool wtap_file_discard_decryption_secrets(wtap *wth);

/**
 * @brief Close all file descriptors for the current wiretap file.
 *
 * Releases both sequential and random-access file handles.
 *
 * @param wth Wiretap file handle.
 */
WS_DLL_PUBLIC
void wtap_fdclose(wtap *wth);

/**
 * @brief Reopen the random-access file descriptor for the current file.
 *
 * Useful when switching access modes or recovering from descriptor loss.
 *
 * @param wth Wiretap file handle.
 * @param filename Path to the file to reopen.
 * @param err Pointer to an error code variable.
 * @return True on success; false on failure.
 */
WS_DLL_PUBLIC
bool wtap_fdreopen(wtap *wth, const char *filename, int *err);

/**
 * @brief Close the sequential-access side of the file.
 *
 * Frees memory associated with buffered reads while retaining random-access capability.
 *
 * @param wth Wiretap file handle.
 */
WS_DLL_PUBLIC
void wtap_sequential_close(wtap *wth);

/**
 * @brief Fully close the wiretap file and release all resources.
 *
 * Closes any open file handles and frees memory associated with the wiretap handle.
 *
 * @param wth Wiretap file handle.
 */
WS_DLL_PUBLIC
void wtap_close(wtap *wth);

/**
 * @brief Check if a file type can be opened for dumping.
 *
 * Determines whether the specified file type supports writing packet data.
 *
 * @param filetype File type identifier.
 * @return True if dumping is supported; false otherwise.
 */
WS_DLL_PUBLIC
bool wtap_dump_can_open(int filetype);

/**
 * @brief Determine the required per-file encapsulation type.
 *
 * Given an array of WTAP_ENCAP_ types, returns the appropriate per-file encapsulation
 * type needed to write a file containing all of them. May return WTAP_ENCAP_PER_PACKET
 * if multiple types are present and the format supports it.
 *
 * @param file_encaps GArray of WTAP_ENCAP_ values.
 * @return Required per-file encapsulation type.
 */
WS_DLL_PUBLIC
int wtap_dump_required_file_encap_type(const GArray *file_encaps);

/**
 * @brief Check if a file type/subtype supports writing a given encapsulation.
 *
 * Returns true if the specified encapsulation type can be written in the given
 * file format; false otherwise.
 *
 * @param file_type_subtype File type/subtype identifier.
 * @param encap Encapsulation type (WTAP_ENCAP_...).
 * @return True if supported; false if not.
 */
WS_DLL_PUBLIC
bool wtap_dump_can_write_encap(int file_type_subtype, int encap);

/**
 * @brief Check if a file type/subtype supports compression.
 *
 * Returns true if the specified file format can be written in compressed form.
 *
 * @param file_type_subtype File type/subtype identifier.
 * @return True if compression is supported; false otherwise.
 */
WS_DLL_PUBLIC
bool wtap_dump_can_compress(int file_type_subtype);

/**
 * @brief Initialize the per-file information based on an existing file.
 *
 * Its contents must be freed according to the requirements of wtap_dump_params.
 * If wth does not remain valid for the duration of the session, dsbs_growing
 * MUST be cleared after this function.
 *
 * @param params The parameters for wtap_dump_* to initialize.
 * @param wth The wiretap session.
 */
WS_DLL_PUBLIC
void wtap_dump_params_init(wtap_dump_params *params, wtap *wth);

/**
 * @brief Initialize the per-file information based on an existing file, but
 * don't copy over the interface information.
 *
 * Its contents must be freed
 * according to the requirements of wtap_dump_params.
 * If wth does not remain valid for the duration of the session, dsbs_growing
 * MUST be cleared after this function.
 *
 * XXX - this should eventually become wtap_dump_params_init(), with all
 * programs writing capture files copying IDBs over by hand, so that they
 * handle IDBs in the middle of the file.
 *
 * @param params The parameters for wtap_dump_* to initialize.
 * @param wth The wiretap session.
 */
WS_DLL_PUBLIC
void wtap_dump_params_init_no_idbs(wtap_dump_params *params, wtap *wth);

/**
 * @brief Remove any name resolution information from the per-file information;
 * used if we're stripping name resolution as we write the file.
 *
 * @param params The parameters for wtap_dump_* from which to remove the
 * name resolution..
 */
WS_DLL_PUBLIC
void wtap_dump_params_discard_name_resolution(wtap_dump_params *params);

/**
 * @brief Remove any decryption secret information from the per-file information;
 * used if we're stripping decryption secrets as we write the file.
 *
 * @param params The parameters for wtap_dump_* from which to remove the
 * decryption secrets..
 */
WS_DLL_PUBLIC
void wtap_dump_params_discard_decryption_secrets(wtap_dump_params *params);

/**
 * @brief Free memory associated with the wtap_dump_params when it is no longer in
 * use by wtap_dumper.
 *
 * @param params The parameters as initialized by wtap_dump_params_init.
 */
WS_DLL_PUBLIC
void wtap_dump_params_cleanup(wtap_dump_params *params);

/**
 * @brief Opens a new capture file for writing.
 *
 * @param filename The new file's name.
 * @param file_type_subtype The WTAP_FILE_TYPE_SUBTYPE_XXX file type.
 * @param compression_type Type of compression to use when writing, if any
 * @param params The per-file information for this file.
 * @param[out] err Will be set to an error code on failure.
 * @param[out] err_info for some errors, a string giving more details of
 * the error
 * @return The newly created dumper object, or NULL on failure.
 */
WS_DLL_PUBLIC
wtap_dumper* wtap_dump_open(const char *filename, int file_type_subtype,
    ws_compression_type compression_type, const wtap_dump_params *params,
    int *err, char **err_info);

/**
 * @brief Creates a dumper for a temporary file.
 *
 * @param tmpdir Directory in which to create the temporary file.
 * @param filenamep Points to a pointer that's set to point to the
 *        pathname of the temporary file; it's allocated with g_malloc()
 * @param pfx A string to be used as the prefix for the temporary file name
 * @param file_type_subtype The WTAP_FILE_TYPE_SUBTYPE_XXX file type.
 * @param compression_type Type of compression to use when writing, if any
 * @param params The per-file information for this file.
 * @param[out] err Will be set to an error code on failure.
 * @param[out] err_info for some errors, a string giving more details of
 * the error
 * @return The newly created dumper object, or NULL on failure.
 */
WS_DLL_PUBLIC
wtap_dumper* wtap_dump_open_tempfile(const char *tmpdir, char **filenamep,
    const char *pfx,
    int file_type_subtype, ws_compression_type compression_type,
    const wtap_dump_params *params, int *err, char **err_info);

/**
 * @brief Creates a dumper for an existing file descriptor.
 *
 * @param fd The file descriptor for which the dumper should be created.
 * @param file_type_subtype The WTAP_FILE_TYPE_SUBTYPE_XXX file type.
 * @param compression_type Type of compression to use when writing, if any
 * @param params The per-file information for this file.
 * @param[out] err Will be set to an error code on failure.
 * @param[out] err_info for some errors, a string giving more details of
 * the error
 * @return The newly created dumper object, or NULL on failure.
 */
WS_DLL_PUBLIC
wtap_dumper* wtap_dump_fdopen(int fd, int file_type_subtype,
    ws_compression_type compression_type, const wtap_dump_params *params,
    int *err, char **err_info);

/**
 * @brief Creates a dumper for the standard output.
 *
 * @param file_type_subtype The WTAP_FILE_TYPE_SUBTYPE_XXX file type.
 * @param compression_type Type of compression to use when writing, if any
 * @param params The per-file information for this file.
 * @param[out] err Will be set to an error code on failure.
 * @param[out] err_info for some errors, a string giving more details of
 * the error
 * @return The newly created dumper object, or NULL on failure.
 */
WS_DLL_PUBLIC
wtap_dumper* wtap_dump_open_stdout(int file_type_subtype,
    ws_compression_type compression_type, const wtap_dump_params *params,
    int *err, char **err_info);

/**
 * @brief Add an IDB to the list of IDBs for a file we're writing.
 * Makes a copy of the IDB, so it can be freed after this call is made.
 *
 * @param wdh handle for the file we're writing.
 * @param idb the IDB to add
 * @param[out] err Will be set to an error code on failure.
 * @param[out] err_info for some errors, a string giving more details of
 * the error.
 * @return true on success, false on failure.
 */
WS_DLL_PUBLIC
bool wtap_dump_add_idb(wtap_dumper *wdh, wtap_block_t idb, int *err,
     char **err_info);

/**
 * @brief Write a record to the dump file.
 *
 * @param wdh handle for the file we're writing.
 * @param rec the record to write.
 * @param[out] err Will be set to an error code on failure.
 * @param[out] err_info for some errors, a string giving more details of
 * the error.
 * @return true on success, false on failure.
 */
WS_DLL_PUBLIC
bool wtap_dump(wtap_dumper *wdh, const wtap_rec *rec, int *err, char **err_info);

/**
 * @brief Flushes the dump file.
 *
 * @param wdh Pointer to the wtap_dumper structure.
 * @param err Pointer to an integer where any error code will be stored.
 * @return true if the flush was successful, false otherwise.
 */
WS_DLL_PUBLIC
bool wtap_dump_flush(wtap_dumper *wdh, int *err);

/**
 * @brief Get the file type subtype of a dump file.
 *
 * @param wdh Pointer to the wtap_dumper structure.
 * @return The file type subtype.
 */
WS_DLL_PUBLIC
int wtap_dump_file_type_subtype(const wtap_dumper *wdh);

/**
 * @brief Get the number of bytes dumped by a packet capture.
 *
 * @param wdh Pointer to the wtap_dumper structure.
 * @return uint64_t The number of bytes dumped.
 */
WS_DLL_PUBLIC
uint64_t wtap_get_bytes_dumped(const wtap_dumper *wdh);

/**
 * @brief Set the number of bytes dumped by a capture file.
 *
 * @param wdh Pointer to the wtap_dumper structure.
 * @param bytes_dumped The number of bytes that have been dumped.
 */
WS_DLL_PUBLIC
void wtap_set_bytes_dumped(wtap_dumper *wdh, uint64_t bytes_dumped);

struct addrinfo;

/**
 * @brief Checks if the address information list is empty.
 *
 * @param addrinfo_lists The address information lists to check.
 * @return true if the list is empty, false otherwise.
 */
WS_DLL_PUBLIC
bool wtap_addrinfo_list_empty(const addrinfo_lists_t *addrinfo_lists);

/**
 * @brief Set the address information list for a dump file.
 *
 * @param wdh handle for the file we're writing.
 * @param addrinfo_lists the address information lists to set
 * @return true on success, false on failure.
 */
WS_DLL_PUBLIC
bool wtap_dump_set_addrinfo_list(wtap_dumper *wdh, addrinfo_lists_t *addrinfo_lists);

/**
 * @brief Discard name resolution information for a dump file.
 *
 * @param wdh The wtap_dumper structure representing the dump file.
 */
WS_DLL_PUBLIC
void wtap_dump_discard_name_resolution(wtap_dumper *wdh);

/**
 * @brief Discard decryption secrets for a dump file.
 *
 * @param wdh The wtap_dumper structure representing the dump file.
 */
WS_DLL_PUBLIC
void wtap_dump_discard_decryption_secrets(wtap_dumper *wdh);

/**
 * Closes open file handles and frees memory associated with wdh. Note that
 * shb_hdr and idb_inf are not freed by this routine.
 *
 * @param wdh handle for the file we're closing.
 * @param[out] needs_reload if not null, points to a bool that will
 *    be set to true if a full reload of the file would be required if
 *    this was done as part of a "Save" or "Save As" operation, false
 *    if no full reload would be required.
 * @param[out] err points to an int that will be set to an error code
 *    on failure.
 * @param[out] err_info for some errors, points to a char * that will
 *    be set to a string giving more details of the error.
 *
 * @return true on success, false on failure.
 */
WS_DLL_PUBLIC
bool wtap_dump_close(wtap_dumper *wdh, bool *needs_reload,
    int *err, char **err_info);

/**
 * @brief Determine whether a capture file can be written with the specified options.
 *
 * Returns true if a capture file can be created that supports all encapsulation
 * types listed in @p file_encaps and supports all comment types indicated by
 * the @p required_comment_types bitmask.
 *
 * The encapsulation list is a GArray of WTAP_ENCAP_ values. The comment types
 * bitmask uses WTAP_COMMENT_TYPE_ flags that indicate which comment features
 * (per-packet, per-file, per-block, etc.) must be supported by the output format.
 *
 * @param file_encaps GArray of WTAP_ENCAP_ values representing packet encapsulations required.
 * @param required_comment_types Bitmask of required comment type flags.
 * @return True if at least one file format/subtype can be written that satisfies
 *         both the encapsulation requirements and the comment type requirements; false otherwise.
 */
WS_DLL_PUBLIC
bool wtap_dump_can_write(const GArray *file_encaps, uint32_t required_comment_types);

/**
 * @brief Generates arbitrary packet data in "exported PDU" format
 * and appends it to buf.
 *
 * For filetype readers to transform non-packetized data.
 * Calls ws_buffer_asssure_space() for you and handles padding
 * to 4-byte boundary.
 *
 * @param[in,out] buf   Buffer into which to write field
 * @param epdu_tag      tag ID of field to create
 * @param data          data to be written
 * @param data_len      length of data
 */
WS_DLL_PUBLIC
void wtap_buffer_append_epdu_tag(Buffer *buf, uint16_t epdu_tag, const uint8_t *data, uint16_t data_len);

/**
 * @brief Generates packet data for an unsigned integer in "exported PDU" format.
 * For filetype readers to transform non-packetized data.
 *
 * @param[in,out] buf   Buffer into which to write field
 * @param epdu_tag      tag ID of field to create
 * @param val           integer value to write to buf
 */
WS_DLL_PUBLIC
void wtap_buffer_append_epdu_uint(Buffer *buf, uint16_t epdu_tag, uint32_t val);

/**
 * @brief Generates packet data for a string in "exported PDU" format.
 * For filetype readers to transform non-packetized data.
 *
 * @param[in,out] buf   Buffer into which to write field
 * @param epdu_tag      tag ID of field to create
 * @param val           string value to write to buf
 */
WS_DLL_PUBLIC
void wtap_buffer_append_epdu_string(Buffer *buf, uint16_t epdu_tag, const char *val);

/**
 * @brief Close off a set of "exported PDUs" added to the buffer.
 * For filetype readers to transform non-packetized data.
 *
 * @param[in,out] buf   Buffer into which to write field
 *
 * @return Total length of buf populated to date
 */
WS_DLL_PUBLIC
int wtap_buffer_append_epdu_end(Buffer *buf);

/**
 * @brief Controls the sort key used when enumerating or presenting file type lists.
 */
typedef enum {
    FT_SORT_BY_NAME,        /**< Sort file types alphabetically by their short internal name */
    FT_SORT_BY_DESCRIPTION  /**< Sort file types alphabetically by their human-readable description */
} ft_sort_order;

/**
 * @brief Get savable file type/subtype candidates for saving a capture file.
 *
 * Get a GArray of file type/subtype values for file types/subtypes
 * that can be used to save a file of a given type with a given GArray of
 * WTAP_ENCAP_ types and the given bitmask of comment types.
 *
 * The returned GArray contains int values (file type/subtype identifiers)
 * and must be freed with g_array_unref() by the caller.
 *
 * @param file_type_subtype File type/subtype identifier of the source file.
 * @param file_encaps GArray of WTAP_ENCAP_ values representing required encapsulations.
 * @param required_comment_types Bitmask of required comment type flags.
 * @param sort_order Ordering to apply to the returned list (ft_sort_order).
 * @return GArray* of int file type/subtype values, or NULL if none are available.
 */
WS_DLL_PUBLIC
GArray *wtap_get_savable_file_types_subtypes_for_file(int file_type_subtype,
    const GArray *file_encaps, uint32_t required_comment_types,
    ft_sort_order sort_order);

/**
 * @brief Get a list of all writable file type/subtype values.
 *
 * Returns a GArray containing all registered file type/subtype identifiers
 * that support writing (dumping) capture files. The array elements are
 * int values representing file type/subtype identifiers and must be freed
 * with g_array_unref() by the caller.
 *
 * @param sort_order Ordering to apply to the returned list (ft_sort_order).
 * @return GArray* of int file type/subtype values, or NULL if none are available.
 */
WS_DLL_PUBLIC
GArray *wtap_get_writable_file_types_subtypes(ft_sort_order sort_order);

/*** various file type/subtype functions ***/
/**
 * @brief Get a human-readable description for a file type/subtype.
 *
 * Returns a descriptive string suitable for UI display or logs that describes
 * the given file type/subtype.
 *
 * @param file_type_subtype File type/subtype identifier.
 * @return Pointer to a static string describing the file type/subtype, or NULL if unknown.
 */
WS_DLL_PUBLIC
const char *wtap_file_type_subtype_description(int file_type_subtype);

/**
 * @brief Get a short name for a file type/subtype.
 *
 * Returns a concise, programmer-friendly name for the given file type/subtype.
 *
 * @param file_type_subtype File type/subtype identifier.
 * @return Pointer to a static string containing the short name, or NULL if unknown.
 */
WS_DLL_PUBLIC
const char *wtap_file_type_subtype_name(int file_type_subtype);

/**
 * @brief Convert a file type/subtype name to its identifier.
 *
 * Parses a short name (as returned by wtap_file_type_subtype_name) and returns
 * the corresponding file type/subtype identifier.
 *
 * @param name Short name string for the file type/subtype.
 * @return File type/subtype identifier on success, or -1 if the name is not recognized.
 */
WS_DLL_PUBLIC
int wtap_name_to_file_type_subtype(const char *name);

/**
 * @brief Get the file type/subtype identifier for classic pcap (microsecond timestamps).
 *
 * @return File type/subtype identifier for pcap.
 */
WS_DLL_PUBLIC
int wtap_pcap_file_type_subtype(void);

/**
 * @brief Get the file type/subtype identifier for pcap with nanosecond timestamps.
 *
 * @return File type/subtype identifier for pcap with nanosecond precision.
 */
WS_DLL_PUBLIC
int wtap_pcap_nsec_file_type_subtype(void);

/**
 * @brief Get the file type/subtype identifier for pcapng.
 *
 * @return File type/subtype identifier for pcapng.
 */
WS_DLL_PUBLIC
int wtap_pcapng_file_type_subtype(void);

/**
 * @brief Determine whether a capture file format supports a given block type.
 *
 * Returns how the specified file type/subtype handles the supplied block type,
 * indicating whether the block is supported, optional, required, or not supported.
 *
 * @param file_type_subtype File type/subtype identifier.
 * @param type Block type to query (wtap_block_type_t).
 * @return block_support_t value describing support level for the block in the format.
 */
WS_DLL_PUBLIC
block_support_t wtap_file_type_subtype_supports_block(int file_type_subtype,
    wtap_block_type_t type);

/**
 * @brief Determine whether a capture file format supports a specific option for a block.
 *
 * Queries the support level for the given option type within the specified block
 * for a particular file type/subtype.
 *
 * The returned value indicates whether the option is supported, optional,
 * required, or not supported in that file format/subtype.
 *
 * @param file_type_subtype File type/subtype identifier.
 * @param type Block type to query (wtap_block_type_t).
 * @param opttype Option type identifier (option type number).
 * @return option_support_t value describing the support level for the option.
 */
WS_DLL_PUBLIC
option_support_t wtap_file_type_subtype_supports_option(int file_type_subtype,
    wtap_block_type_t type, unsigned opttype);

/**
 *@brief Return a list of all extensions that are used by all capture file
 * types, including compressed extensions, e.g. not just "pcap" but
 * also "pcap.gz" if we can read gzipped files.
 *
 * "Capture files" means "include file types that correspond to
 * collections of network packets, but not file types that
 * store data that just happens to be transported over protocols
 * such as HTTP but that aren't collections of network packets",
 * so that it could be used for "All Capture Files" without picking
 * up JPEG files or files such as that - those aren't capture files,
 * and we *do* have them listed in the long list of individual file
 * types, so omitting them from "All Capture Files" is the right
 * thing to do.
 *
 * All strings in the list are allocated with g_malloc() and must be freed
 * with g_free().
 *
 * This is used to generate a list of extensions to look for if the user
 * chooses "All Capture Files" in a file open dialog.
 *
 * @return GSList* of char* strings containing file extensions; NULL if none are known.
 */
WS_DLL_PUBLIC
GSList *wtap_get_all_capture_file_extensions_list(void);

/**
 * @brief Return a list of all extensions that are used by all file types that
 * we can read, including compressed extensions, e.g. not just "pcap" but
 * also "pcap.gz" if we can read gzipped files.
 *
 * "File type" means "include file types that correspond to collections
 * of network packets, as well as file types that store data that just
 * happens to be transported over protocols such as HTTP but that aren't
 * collections of network packets, and plain text files".
 *
 * All strings in the list are allocated with g_malloc() and must be freed
 * with g_free().
 *
 * @return GSList* of char* strings containing file extensions; NULL if none are known.
 */
WS_DLL_PUBLIC
GSList *wtap_get_all_file_extensions_list(void);

/**
 * @brief Free a list of file extension strings returned by extension helpers.
 *
 * Frees the GSList and each string it contains. The list must have been
 * returned by one of:
 * - wtap_get_file_extension_type_extensions()
 * - wtap_get_all_capture_file_extensions_list()
 * - wtap_get_file_extensions_list()
 * - wtap_get_all_file_extensions_list()
 *
 * Each string in the list is freed with g_free() before the list itself is freed.
 *
 * @param extensions GSList of char* strings to free; may be NULL.
 */
WS_DLL_PUBLIC
void wtap_free_extensions_list(GSList *extensions);

/**
 * @brief Get the default file extension for a file type/subtype.
 *
 * Returns the canonical, unprefixed extension (without a leading ".") to use
 * when saving files of the specified file type/subtype.
 *
 * The returned string is owned by the library and must not be freed by the caller.
 *
 * @param file_type_subtype File type/subtype identifier.
 * @return Pointer to a static string containing the default extension, or NULL if unknown.
 */
WS_DLL_PUBLIC
const char *wtap_default_file_extension(int file_type_subtype);

/**
 * @brief Return a list of file extensions that are used by the specified file type
 * and subtype.
 *
 * If include_compressed is true, the list will include compressed
 * extensions, e.g. not just "pcap" but also "pcap.gz" if we can read
 * gzipped files.
 *
 * All strings in the list are allocated with g_malloc() and must be freed
 * with g_free().
 *
 * @param file_type_subtype File type/subtype identifier.
 * @param include_compressed True to include compressed extensions; false to include only uncompressed ones.
 * @return GSList* of char* strings containing file extensions; NULL if none are known.
 */
WS_DLL_PUBLIC
GSList *wtap_get_file_extensions_list(int file_type_subtype, bool include_compressed);

/**
 * @brief Get a short name for an encapsulation type.
 *
 * Returns a short, programmer-friendly name for the given WTAP_ENCAP_ value.
 *
 * @param encap Encapsulation type (WTAP_ENCAP_...).
 * @return Pointer to a static string containing the short name, or NULL if unknown.
 */
WS_DLL_PUBLIC
const char *wtap_encap_name(int encap);

/**
 * @brief Get a human-readable description for an encapsulation type.
 *
 * Returns a descriptive string suitable for UI display or logs describing the encapsulation.
 *
 * @param encap Encapsulation type (WTAP_ENCAP_...).
 * @return Pointer to a static string containing the description, or NULL if unknown.
 */
WS_DLL_PUBLIC
const char *wtap_encap_description(int encap);

/**
 * @brief Convert a short encapsulation name to its WTAP_ENCAP_ value.
 *
 * Parses a short encap name (as returned by wtap_encap_name) and returns the corresponding
 * encapsulation constant.
 *
 * @param short_name Short encap name string.
 * @return WTAP_ENCAP_ value on success, or -1 if the name is not recognized.
 */
WS_DLL_PUBLIC
int wtap_name_to_encap(const char *short_name);

/**
 * @brief Convert a timestamp precision constant to a string.
 *
 * Returns a short string describing the timestamp precision (e.g., "microsecond", "nanosecond").
 *
 * @param tsprec Timestamp precision constant (WTAP_TSPREC_...).
 * @return Pointer to a static string describing the precision, or NULL if unknown.
 */
WS_DLL_PUBLIC
const char* wtap_tsprec_string(int tsprec);

/**
 * @brief Return a human-readable error string for a WTAP error code.
 *
 * Maps wiretap error codes to descriptive strings for logging and diagnostics.
 *
 * @param err WTAP error code.
 * @return Pointer to a static string describing the error, or a generic message if unknown.
 */
WS_DLL_PUBLIC
const char *wtap_strerror(int err);


/*** get available number of file types and encapsulations ***/
/**
 * @brief Return the number of registered file type extension groups.
 *
 * Returns the count of known file type extension entries (the number of
 * different file type / extension groups the library knows about).
 *
 * @return Number of file type extension entries.
 */
WS_DLL_PUBLIC
int wtap_get_num_file_type_extensions(void);

/**
 * @brief Return the number of known encapsulation types.
 *
 * Returns the count of WTAP_ENCAP_ values the library recognizes.
 *
 * @return Number of encapsulation types.
 */
WS_DLL_PUBLIC
int wtap_get_num_encap_types(void);

/*** get information for file type extension ***/

/**
 * @brief Get the short name for a file extension type.
 *
 * Returns a short, programmer-friendly name for the given file extension
 * type identifier (for example, a canonical key used in UI lists).
 *
 * The returned string is owned by the library and must not be freed by the caller.
 *
 * @param extension_type File extension type identifier.
 * @return Pointer to a static string containing the short name, or NULL if unknown.
 */
WS_DLL_PUBLIC
const char *wtap_get_file_extension_type_name(int extension_type);

/**
 * @brief Get the list of extensions for a file extension type.
 *
 * Returns a GSList of strings containing the file extensions associated with
 * the specified extension type. Each string is allocated with g_malloc() and
 * must be freed with g_free() by the caller. The list itself should be freed
 * with wtap_free_extensions_list().
 *
 * @param extension_type File extension type identifier.
 * @return GSList* of char* strings containing extensions (without leading '.'), or NULL if none are known.
 */
WS_DLL_PUBLIC
GSList *wtap_get_file_extension_type_extensions(unsigned extension_type);

/*** dynamically register new file types and encapsulations ***/

/**
 * @brief Register file extension information for a file type.
 *
 * Dynamically registers a new file type's extension metadata so the library
 * can recognize and present the extensions in UI lists and file dialogs.
 *
 * The caller retains ownership of @p ei; the function will copy or reference
 * the data as needed according to the library's registration semantics.
 *
 * @param ei Pointer to a file_extension_info structure describing the file type's extensions.
 */
WS_DLL_PUBLIC
void wtap_register_file_type_extension(const struct file_extension_info *ei);

/**
 * @brief Plugin registration callback table.
 *
 * Implementations of wiretap modules should populate this structure and pass
 * it to wtap_register_plugin to have their registration routine invoked at
 * library initialization or plugin registration time.
 *
 * @field register_wtap_module Function pointer called to register the wiretap module.
 *                            May be NULL if the plugin has no registration routine.
 */
typedef struct {
    void (*register_wtap_module)(void);
} wtap_plugin;

/**
 * @brief Register a wiretap plugin.
 *
 * Registers a plugin with the library. If the plugin provides a
 * register_wtap_module callback, that callback will be invoked to perform
 * module-specific registrations (file formats, encapsulations, extensions, etc.).
 *
 * The caller retains ownership of @p plug.
 *
 * @param plug Pointer to a wtap_plugin describing the plugin's registration callback(s).
 */
WS_DLL_PUBLIC
void wtap_register_plugin(const wtap_plugin *plug);


/**
 * @brief Query whether libwiretap plugin loading is available.
 *
 * Returns a status code indicating whether libwiretap can load plugins on
 * the current platform and build configuration.
 *
 * Return values:
 *   0  Plugins can be loaded for libwiretap (file type).
 *   1  Plugins are not supported by the platform.
 *  -1  Plugins were disabled in the build configuration.
 *
 * @return int status code as described above.
 */
WS_DLL_PUBLIC
int wtap_plugins_supported(void);

/* Registration and open-info */

/**
 * @brief Register an open_info probe/open handler.
 * @param oi Pointer to open_info descriptor.
 * @param first_routine If true, insert at front of probe list.
 */
WS_DLL_PUBLIC
void wtap_register_open_info(struct open_info *oi, const bool first_routine);

/**
 * @brief Check if an open_info handler with the given name is registered.
 * @param name Short name of the handler.
 * @return true if registered, false otherwise.
 */
WS_DLL_PUBLIC
bool wtap_has_open_info(const char *name);

/**
 * @brief Check whether a wtap handle uses a Lua-based file handler.
 * @param wth Pointer to wtap handle.
 * @return true if backed by a Lua filehandler, false otherwise.
 */
WS_DLL_PUBLIC
bool wtap_uses_lua_filehandler(const wtap* wth);

/**
 * @brief Deregister an open_info handler by name.
 * @param name Short name of the handler to remove.
 */
WS_DLL_PUBLIC
void wtap_deregister_open_info(const char *name);

/* Type mapping and registration */

/**
 * @brief Convert an open_info short name to its numeric type.
 * @param name Short name.
 * @return Unsigned type identifier (implementation-defined sentinel if not found).
 */
WS_DLL_PUBLIC
unsigned int open_info_name_to_type(const char *name);

/**
 * @brief Register a file type/subtype.
 * @param fi Pointer to file_type_subtype_info.
 * @return non-negative file_type_subtype id on success, negative on failure.
 */
WS_DLL_PUBLIC
int wtap_register_file_type_subtype(const struct file_type_subtype_info* fi);

/**
 * @brief Deregister a previously registered file type/subtype.
 * @param file_type_subtype Identifier returned by registration.
 */
WS_DLL_PUBLIC
void wtap_deregister_file_type_subtype(const int file_type_subtype);

/* Encapsulation and cleanup */
/**
 * @brief Register a new packet encapsulation type.
 * @param description Human-readable description.
 * @param name Short canonical name.
 * @return Encapsulation id on success, negative on failure.
 */
WS_DLL_PUBLIC
int wtap_register_encap_type(const char *description, const char *name);

/**
 * @brief Clean up libwiretap internal registrations and plugin state.
 */
WS_DLL_PUBLIC
void wtap_cleanup(void);

/**
 * Wiretap error codes.
 */
#define WTAP_ERR_NOT_REGULAR_FILE              -1
    /**< The file being opened for reading isn't a plain file (or pipe) */

#define WTAP_ERR_RANDOM_OPEN_PIPE              -2
    /**< The file is being opened for random access and it's a pipe */

#define WTAP_ERR_FILE_UNKNOWN_FORMAT           -3
    /**< The file being opened is not a capture file in a known format */

#define WTAP_ERR_UNSUPPORTED                   -4
    /**< Supported file type, but there's something in the file we're
       reading that we can't support */

#define WTAP_ERR_CANT_WRITE_TO_PIPE            -5
    /**< Wiretap can't save to a pipe in the specified format */

#define WTAP_ERR_CANT_OPEN                     -6
    /**< The file couldn't be opened, reason unknown */

#define WTAP_ERR_UNWRITABLE_FILE_TYPE          -7
    /**< Wiretap can't save files in the specified format */

#define WTAP_ERR_UNWRITABLE_ENCAP              -8
    /**< Wiretap can't read or save files in the specified format with the
       specified encapsulation */

#define WTAP_ERR_ENCAP_PER_PACKET_UNSUPPORTED  -9
    /**< The specified format doesn't support per-packet encapsulations */

#define WTAP_ERR_CANT_WRITE                   -10
    /**< An attempt to read failed, reason unknown */

#define WTAP_ERR_CANT_CLOSE                   -11
    /**< The file couldn't be closed, reason unknown */

#define WTAP_ERR_SHORT_READ                   -12
    /**< An attempt to read less data than it should have */

#define WTAP_ERR_BAD_FILE                     -13
    /**< The file appears to be damaged or corrupted or otherwise bogus */

#define WTAP_ERR_SHORT_WRITE                  -14
    /**< An attempt to write wrote less data than it should have */

#define WTAP_ERR_UNC_OVERFLOW                 -15
    /**< Uncompressing Sniffer data would overflow buffer */

#define WTAP_ERR_RANDOM_OPEN_STDIN            -16
    /**< We're trying to open the standard input for random access */

#define WTAP_ERR_COMPRESSION_NOT_SUPPORTED    -17
    /**< The filetype doesn't support output compression */

#define WTAP_ERR_CANT_SEEK                    -18
    /**< An attempt to seek failed, reason unknown */

#define WTAP_ERR_CANT_SEEK_COMPRESSED         -19
    /**< An attempt to seek on a compressed stream */

#define WTAP_ERR_DECOMPRESS                   -20
    /**< Error decompressing */

#define WTAP_ERR_INTERNAL                     -21
    /**< "Shouldn't happen" internal errors */

#define WTAP_ERR_PACKET_TOO_LARGE             -22
    /**< Packet being written is larger than we support; do not use when
        reading, use WTAP_ERR_BAD_FILE instead */

#define WTAP_ERR_CHECK_WSLUA                  -23
    /**< Not really an error: the file type being checked is from a Lua
        plugin, so that the code will call wslua_can_write_encap() instead if it gets this */

#define WTAP_ERR_UNWRITABLE_REC_TYPE          -24
    /**< Specified record type can't be written to that file type */

#define WTAP_ERR_UNWRITABLE_REC_DATA          -25
    /**< Something in the record data can't be written to that file type */

#define WTAP_ERR_DECOMPRESSION_NOT_SUPPORTED  -26
    /**< We don't support decompressing that type of compressed file */

#define WTAP_ERR_TIME_STAMP_NOT_SUPPORTED     -27
    /**< We don't support writing that record's time stamp to that
         file type  */

#define WTAP_ERR_REC_MALFORMED		      -28
	 /**< Packet being read is of a known type, but is malformed so it will be skipped.
	     This can be used instead of WTAP_ERR_BAD_FILE to not stop reading of a file */

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* __WTAP_H__ */

/*
 * Editor modelines  -  https://www.wireshark.org/tools/modelines.html
 *
 * Local variables:
 * c-basic-offset: 4
 * tab-width: 8
 * indent-tabs-mode: nil
 * End:
 *
 * vi: set shiftwidth=4 tabstop=8 expandtab:
 * :indentSize=4:tabSize=8:noTabs=true:
 */
