Module org.pcap4j.core
Package org.pcap4j.core

Class PcapHandle

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

    • Field Detail

      • logger

        private static final org.slf4j.Logger logger

      • handle

        private final com.sun.jna.Pointer handle

      • timestamps

        private final java.lang.ThreadLocal<java.sql.Timestamp> timestamps

      • originalLengths

        private final java.lang.ThreadLocal<java.lang.Integer> originalLengths

      • handleLock

        private final java.util.concurrent.locks.ReentrantReadWriteLock handleLock

      • compileLock

        private static final java.lang.Object compileLock

      • open

        private volatile boolean open

      • filteringExpression

        private volatile java.lang.String filteringExpression

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

      • getTimestamp

        public java.sql.Timestamp getTimestamp()
        Returns:
        the timestamp of the last packet captured by this handle in the current thread.

      • getOriginalLength

        public java.lang.Integer getOriginalLength()
        Returns:
        the original length of the last packet captured by this handle in the current thread.

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

      • getNextPacket

        public Packet getNextPacket()
                     throws NotOpenException
        Returns:
        a Packet object created from a captured packet using the packet factory. May be null.
        Throws:
        NotOpenException - if this PcapHandle is not open.

      • getNextRawPacket

        public byte[] getNextRawPacket()
                        throws NotOpenException
        Returns:
        a captured packet. May be null.
        Throws:
        NotOpenException - if this PcapHandle is not open.

      • getNextPacketEx

        public Packet getNextPacketEx()
                       throws PcapNativeException,
                              java.io.EOFException,
                              java.util.concurrent.TimeoutException,
                              NotOpenException
        Returns:
        a Packet object created from a captured packet using the packet factory. 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.

      • getNextRawPacketEx

        public byte[] getNextRawPacketEx()
                          throws PcapNativeException,
                                 java.io.EOFException,
                                 java.util.concurrent.TimeoutException,
                                 NotOpenException
        Returns:
        a 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.

      • loop

        public void loop​(int packetCount,
                 RawPacketListener listener)
          throws PcapNativeException,
                 java.lang.InterruptedException,
                 NotOpenException
        A wrapper method for int pcap_loop(pcap_t *, int, pcap_handler, u_char *). When a packet is captured, listener.gotPacket(byte[]) 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,
                 RawPacketListener 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 *). 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(byte[]). If listener.gotPacket(byte[]) is expected to take a long time to process a packet, this method should be used with a proper executor instead of loop(int, RawPacketListener) 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.

      • dispatch

        public int dispatch​(int packetCount,
                    RawPacketListener 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,
                    RawPacketListener 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.

      • close

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

      • toString

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

      • buildTimestamp

        private java.sql.Timestamp buildTimestamp​(com.sun.jna.Pointer header)