Package org.pcap4j.core

Class PcapHandle

  • All Implemented Interfaces:
    java.lang.AutoCloseable
    public final class PcapHandle
extends java.lang.Object
implements java.lang.AutoCloseable
    A wrapper class for struct pcap_t.
    Since:
    pcap4j 0.9.1
    Author:
    Kaito Yamada

    • Method Detail

      • getDlt

        public DataLinkType getDlt()
        Returns:
        the Data Link Type of this PcapHandle

      • isOpen

        public boolean isOpen()
        Returns:
        true if this PcapHandle object is open (i.e. not yet closed by close()); false otherwise.

      • getFilteringExpression

        public java.lang.String getFilteringExpression()
        Returns:
        the filtering expression of this PcapHandle

      • setDirection

        public void setDirection​(PcapHandle.PcapDirection direction)
                  throws PcapNativeException,
                         NotOpenException
        Set direction flag, which controls whether we accept only incoming packets, only outgoing packets, or both. Note that, depending on the platform, some or all direction arguments might not be supported.
        Parameters:
        direction - direction to set.
        Throws:
        PcapNativeException - if an error occurs in the pcap native library.
        NotOpenException - if this PcapHandle is not open.

      • getSnapshot

        public int getSnapshot()
                throws NotOpenException
        Returns:
        the dimension of the packet portion (in bytes) that is delivered to the application.
        Throws:
        NotOpenException - if this PcapHandle is not open.

      • getMajorVersion

        public int getMajorVersion()
                    throws NotOpenException
        Returns:
        the major version number of the pcap library used to write the savefile.
        Throws:
        NotOpenException - if this PcapHandle is not open.

      • getMinorVersion

        public int getMinorVersion()
                    throws NotOpenException
        Returns:
        the minor version number of the pcap library used to write the savefile.
        Throws:
        NotOpenException - if this PcapHandle is not open.

      • getNextPacketEx

        public PcapPacket getNextPacketEx()
                           throws PcapNativeException,
                                  java.io.EOFException,
                                  java.util.concurrent.TimeoutException,
                                  NotOpenException
        Returns:
        a PcapPacket object that contains captured packet. Not null.
        Throws:
        PcapNativeException - if an error occurs in the pcap native library.
        java.io.EOFException - if packets are being read from a pcap file and there are no more packets to read from the file.
        java.util.concurrent.TimeoutException - if packets are being read from a live capture and the timeout expired.
        NotOpenException - if this PcapHandle is not open.

      • loop

        public void loop​(int packetCount,
                 PacketListener listener)
          throws PcapNativeException,
                 java.lang.InterruptedException,
                 NotOpenException
        A wrapper method for int pcap_loop(pcap_t *, int, pcap_handler, u_char *). This method creates a Packet object from a captured packet using the packet factory and passes it to listener.gotPacket(Packet). When a packet is captured, listener.gotPacket(Packet) is called in the thread which called the loop(). And then this PcapHandle waits for the thread to return from the gotPacket() before it retrieves the next packet from the pcap buffer.
        Parameters:
        packetCount - the number of packets to capture. -1 is equivalent to infinity. 0 may result in different behaviors between platforms and pcap library versions.
        listener - listener
        Throws:
        PcapNativeException - if an error occurs in the pcap native library.
        java.lang.InterruptedException - if the loop terminated due to a call to breakLoop().
        NotOpenException - if this PcapHandle is not open.

      • loop

        public void loop​(int packetCount,
                 PacketListener listener,
                 java.util.concurrent.Executor executor)
          throws PcapNativeException,
                 java.lang.InterruptedException,
                 NotOpenException
        A wrapper method for int pcap_loop(pcap_t *, int, pcap_handler, u_char *). This method creates a Packet object from a captured packet using the packet factory and passes it to listener.gotPacket(Packet). When a packet is captured, the executor.execute() is called with a Runnable object in the thread which called the loop(). Then, the Runnable object calls listener.gotPacket(Packet). If listener.gotPacket(Packet) is expected to take a long time to process a packet, this method should be used with a proper executor instead of loop(int, PacketListener) in order to prevent the pcap buffer from overflowing.
        Parameters:
        packetCount - the number of packets to capture. -1 is equivalent to infinity. 0 may result in different behaviors between platforms and pcap library versions.
        listener - listener
        executor - executor
        Throws:
        PcapNativeException - if an error occurs in the pcap native library.
        java.lang.InterruptedException - if the loop terminated due to a call to breakLoop().
        NotOpenException - if this PcapHandle is not open.

      • dispatch

        public int dispatch​(int packetCount,
                    PacketListener listener)
             throws PcapNativeException,
                    java.lang.InterruptedException,
                    NotOpenException
        Parameters:
        packetCount - the maximum number of packets to process. If -1 is specified, all the packets in the pcap buffer or pcap file will be processed before returning. 0 may result in different behaviors between platforms and pcap library versions.
        listener - listener
        Returns:
        the number of captured packets.
        Throws:
        PcapNativeException - if an error occurs in the pcap native library.
        java.lang.InterruptedException - if the loop terminated due to a call to breakLoop().
        NotOpenException - if this PcapHandle is not open.

      • dispatch

        public int dispatch​(int packetCount,
                    PacketListener listener,
                    java.util.concurrent.Executor executor)
             throws PcapNativeException,
                    java.lang.InterruptedException,
                    NotOpenException
        Parameters:
        packetCount - the maximum number of packets to process. If -1 is specified, all the packets in the pcap buffer or pcap file will be processed before returning. 0 may result in different behaviors between platforms and pcap library versions.
        listener - listener
        executor - executor
        Returns:
        the number of captured packets.
        Throws:
        PcapNativeException - if an error occurs in the pcap native library.
        java.lang.InterruptedException - if the loop terminated due to a call to breakLoop().
        NotOpenException - if this PcapHandle is not open.

      • dumpOpen

        public PcapDumper dumpOpen​(java.lang.String filePath)
                    throws PcapNativeException,
                           NotOpenException
        Parameters:
        filePath - "-" means stdout. The dlt of the PcapHandle which captured the packets you want to dump must be the same as this dlt.
        Returns:
        an opened PcapDumper.
        Throws:
        PcapNativeException - if an error occurs in the pcap native library.
        NotOpenException - if this PcapHandle is not open.

      • breakLoop

        public void breakLoop()
               throws NotOpenException
        Breaks a loop which this handle is working on.

        The loop may not be broken immediately on some OSes because of buffering or something. As a workaround, letting this capture some bogus packets after calling this method may work.

        Throws:
        NotOpenException - if this PcapHandle is not open.

      • stream

        public java.util.stream.Stream<PcapPacket> stream()
                                           throws NotOpenException
        Returns a Stream instance representing a stream of captured packets. When this handle become unable to capture packets anymore (e.g. reaches EOF of the pcap file), the stream starts to supply nulls. This method locks this handle. Call BaseStream.close() to unlock.
        Returns:
        a stream of captured packets.
        Throws:
        NotOpenException - if this PcapHandle is not open.

      • close

        public void close()
        Closes this PcapHandle.
        Specified by:
        close in interface java.lang.AutoCloseable

      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object