Package pcap.spi

Interface Pcap

All Superinterfaces:
AutoCloseable
public interface Pcap
extends AutoCloseable
A handle for pcap api.
Since:
1.0.0
Author:
Ardika Rommy Sanjaya

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Interface Description
    static class  Pcap.Direction
    Used to specify a direction that packets will be captured.

  • Method Summary

    Modifier and Type Method Description
    <T> T allocate​(Class<T> cls)
    Create empty pointer.
    void breakLoop()
    Force a loop(int, PacketHandler, Object) call to return And throw BreakException on loop(int, PacketHandler, Object).
    void close()
    Close PcapLive or PcapOffline.
    <T> void dispatch​(int count, PacketHandler<T> handler, T args)
    processes packets from a live capture or PcapLive until cnt packets are processed, the end of the current bufferful of packets is reached when doing a live capture, the end of the 'savefile' is reached when reading from a 'savefile', Pcap#breakLoop() is called, or an error occurs.
    Dumper dumpOpen​(String file)
    Open Dumper handler.
    Dumper dumpOpenAppend​(String file)
    Append packet buffer on existing pcap file.
    <T> void loop​(int count, PacketHandler<T> handler, T args)
    Process packets from a live PcapLive or PcapOffline.
    void nextEx​(PacketBuffer packetBuffer, PacketHeader packetHeader)
    Reads the next packet and returns a success/failure indication.
    void send​(ByteBuffer directBuffer, int size)
    Deprecated.
    void send​(PacketBuffer directBuffer, int size)
    Sends a raw packet through the network interface.
    void setDirection​(Pcap.Direction direction)
    Used to specify a direction that packets will be captured.
    void setFilter​(String filter, boolean optimize)
    BPF packet filter.
    void setNonBlock​(boolean blocking)
    Puts a this capture handle into `non-blocking` mode, or takes it out of `non-blocking` mode, depending on whether the nonblock argument is `true` or `false`.
    Status status()
    Represent packet statistics from the start of the run to the time of the call.

  • Method Details

    • dumpOpen

      Dumper dumpOpen​(String file) throws ErrorException
      Open Dumper handler.
      Parameters:
      file - location of capture file will saved.
      Returns:
      returns Pcap Dumper handle.
      Throws:
      ErrorException - generic exception.
      Since:
      1.0.0

    • dumpOpenAppend

      Dumper dumpOpenAppend​(String file) throws ErrorException
      Append packet buffer on existing pcap file.
      Parameters:
      file - location of saved file.
      Returns:
      returns Pcap Dumper handle.
      Throws:
      ErrorException - generic error.
      Since:
      1.0.0

    • setFilter

      void setFilter​(String filter, boolean optimize) throws ErrorException
      BPF packet filter.
      Parameters:
      filter - filter expression.
      optimize - true for optimized filter, false otherwise.
      Throws:
      ErrorException - generic error.
      Since:
      1.0.0

    • loop

      <T> void loop​(int count, PacketHandler<T> handler, T args) throws BreakException, ErrorException
      Process packets from a live PcapLive or PcapOffline.
      Type Parameters:
      T - args type.
      Parameters:
      count - maximum number of packets to process before returning. A value of -1 or 0 for count is equivalent to infinity, so that packets are processed until another ending condition occurs.
      handler - PacketHandler callback function.
      args - user args.
      Throws:
      BreakException - breakLoop() is called.
      ErrorException - Generic error.
      Since:
      1.0.0

    • nextEx

      void nextEx​(PacketBuffer packetBuffer, PacketHeader packetHeader) throws BreakException, TimeoutException, ErrorException
      Reads the next packet and returns a success/failure indication.
      Parameters:
      packetBuffer - packet buffer.
      packetHeader - packet header.
      Throws:
      BreakException - there are no more packets to read from `savefile`.
      TimeoutException - if packets are being read from a `live capture` and the packet buffer timeout expired.
      ErrorException - generic exception.
      Since:
      1.0.0

    • dispatch

      <T> void dispatch​(int count, PacketHandler<T> handler, T args) throws BreakException, ErrorException
      processes packets from a live capture or PcapLive until cnt packets are processed, the end of the current bufferful of packets is reached when doing a live capture, the end of the 'savefile' is reached when reading from a 'savefile', Pcap#breakLoop() is called, or an error occurs. Thus, when doing a live capture, cnt is the maximum number of packets to process before returning, but is not a minimum number; when reading a live capture, only one bufferful of packets is read at a time, so fewer than cnt packets may be processed. A value of -1 or 0 for cnt causes all the packets received in one buffer to be processed when reading a live capture, and causes all the packets in the file to be processed when reading a 'savefile'.

      (In older versions of libpcap, the behavior when cnt was 0 was undefined; different platforms and devices behaved differently, so code that must work with older versions of libpcap should use -1, nor 0, as the value of cnt.)

      callback specifies a PacketHandler routine to be called with three arguments : a args which is passed in the user argument to Pcap#loop() or Pcap#dispatch(), a const struct pcap_pkthdr pointer pointing to the packet time stamp and lengths, and a args to the first caplen bytes of data from the packet.

      (In older versions of libpcap, the behavior when cnt was 0 was undefined; different platforms and devices behaved differently, so code that must work with older versions of libpcap should use -1, nor 0, as the value of cnt.)

      Type Parameters:
      T - args type.
      Parameters:
      count - number of packets.
      handler - PacketHandler callback function.
      args - user args.
      Throws:
      BreakException - breakLoop() is called.
      ErrorException - Generic error.

    • status

      Status status() throws ErrorException
      Represent packet statistics from the start of the run to the time of the call.

      Supported only on live captures, not on PcapOffline; no statistics are stored in PcapOffline so no statistics are available when reading from a PcapOffline

      Returns:
      returns Status on success.
      Throws:
      ErrorException - There is an error or if this Pcap doesn't support packet statistics.
      Since:
      1.0.0

    • breakLoop

      void breakLoop()
      Force a loop(int, PacketHandler, Object) call to return And throw BreakException on loop(int, PacketHandler, Object).
      Since:
      1.0.0

    • send

      @Deprecated void send​(ByteBuffer directBuffer, int size) throws ErrorException
      Deprecated.
      Sends a raw packet through the network interface.
      Parameters:
      directBuffer - the data of the packet, including the link-layer header.
      size - the number of bytes in the packet.
      Throws:
      ErrorException - generic error.

    • send

      void send​(PacketBuffer directBuffer, int size) throws ErrorException
      Sends a raw packet through the network interface.
      Parameters:
      directBuffer - the data of the packet, including the link-layer header.
      size - the number of bytes in the packet.
      Throws:
      ErrorException - generic error.

    • setDirection

      void setDirection​(Pcap.Direction direction) throws ErrorException
      Used to specify a direction that packets will be captured. This method isn't necessarily fully supported on all platforms; some platforms might return an error for all values, and some other platforms might not support Pcap.Direction.PCAP_D_OUT.

      This operation is not supported if a PcapOffline is being read.

      Below is list of directions:

      • PCAP_D_INOUT is the default direction and it will capture packets received by or sent by the device.
      • PCAP_D_IN only capture packets received by the device.
      • PCAP_D_OUT only capture packets sent by the device.
      Parameters:
      direction - is one of the constants Pcap.Direction.
      Throws:
      ErrorException - generic exception.

    • setNonBlock

      void setNonBlock​(boolean blocking) throws ErrorException
      Puts a this capture handle into `non-blocking` mode, or takes it out of `non-blocking` mode, depending on whether the nonblock argument is `true` or `false`. It has no effect on `savefiles`. In `non-blocking` mode, an attempt to read from the capture descriptor with dispatch(int, PacketHandler, Object) will, if no packets are currently available to be read, return void; immediately rather than blocking waiting for packets to arrive. loop(int, PacketHandler, Object) will not work in `non-blocking` mode.
      Parameters:
      blocking - `true` for enable non blocking mode, `false` otherwise.
      Throws:
      ErrorException - throwing some error when calling this method.

    • close

      void close()
      Close PcapLive or PcapOffline.
      Note: BPF handle will closed automaticly.
      Specified by:
      close in interface AutoCloseable
      Since:
      1.0.0

    • allocate

      <T> T allocate​(Class<T> cls) throws IllegalArgumentException
      Create empty pointer.
      Type Parameters:
      T - pointer type.
      Parameters:
      cls - a class, ex PacketHeader and PacketBuffer.
      Returns:
      returns <T> instance.
      Throws:
      IllegalArgumentException