@spec clear_filter(t()) :: :ok | {:error, String.t()}

Clears all pre-filters from the reader.

Examples

{:ok, reader} = PcapFileEx.PcapNg.open("capture.pcapng")
:ok = PcapFileEx.PcapNg.set_filter(reader, [...])
:ok = PcapFileEx.PcapNg.clear_filter(reader)

@spec close(t()) :: :ok

Closes the PCAPNG reader and releases resources.

@spec interfaces(t()) :: {:ok, [PcapFileEx.Interface.t()]} | {:error, String.t()}

Returns metadata for all interfaces discovered in the PCAPNG file.

The interface list is populated lazily as blocks are encountered during reads. Calling next_packet/1 at least once ensures interface metadata is available.

@spec next_packet(t()) :: {:ok, PcapFileEx.Packet.t()} | :eof | {:error, String.t()}

Reads the next packet from the PCAPNG file.

This automatically skips non-packet blocks (like Section Header, Interface Description, etc.) and returns only packet data.

Returns {:ok, packet} if a packet was read, :eof if the end of file was reached, or {:error, reason} if an error occurred.

Options

• :hosts_map - Map of IP address strings to hostname strings for endpoint resolution

Examples

{:ok, reader} = PcapFileEx.PcapNg.open("capture.pcapng")
{:ok, packet} = PcapFileEx.PcapNg.next_packet(reader)
IO.inspect(packet.timestamp)

# With hosts mapping
hosts = %{"192.168.1.1" => "gateway", "10.0.0.1" => "server"}
{:ok, packet} = PcapFileEx.PcapNg.next_packet(reader, hosts_map: hosts)

@spec open(Path.t()) :: {:ok, t()} | {:error, String.t()}

Opens a PCAPNG file for reading.

Examples

iex> {:ok, reader} = PcapFileEx.PcapNg.open("capture.pcapng")
iex> is_struct(reader, PcapFileEx.PcapNg)
true

@spec read_all(Path.t()) :: {:ok, [PcapFileEx.Packet.t()]} | {:error, String.t()}

Reads all packets from the PCAPNG file into a list.

This loads all packets into memory, so be careful with large files.

Returns {:ok, packets} on success or {:error, reason} if a packet fails to parse. On error, the file is still properly closed.

Options

• :hosts_map - Map of IP address strings to hostname strings for endpoint resolution

Examples

{:ok, packets} = PcapFileEx.PcapNg.read_all("capture.pcapng")
Enum.count(packets)

# With hosts mapping
hosts = %{"192.168.1.1" => "gateway"}
{:ok, packets} = PcapFileEx.PcapNg.read_all("capture.pcapng", hosts_map: hosts)

@spec set_filter(t(), [PcapFileEx.PreFilter.filter()]) :: :ok | {:error, String.t()}

Sets pre-filters on the reader for high-performance filtering in the Rust layer.

Filters are applied before packets are deserialized to Elixir, providing 10-100x performance improvement for selective filtering on large files.

See PcapFileEx.PreFilter for available filter types.

Examples

{:ok, reader} = PcapFileEx.PcapNg.open("capture.pcapng")

filters = [
  PcapFileEx.PreFilter.protocol("tcp"),
  PcapFileEx.PreFilter.port_dest(80)
]

:ok = PcapFileEx.PcapNg.set_filter(reader, filters)

# Now next_packet will only return matching packets
{:ok, packet} = PcapFileEx.PcapNg.next_packet(reader)