The pcaplib API reference
=========================

.. automodule:: pcaplib

   .. autoclass:: Reader

      Construct a Reader which reads the content of a PCAP file and can be consumed as an Iterable.
      An :exc:`FileFormatError` is raised if the file is not a valid PCAP file.

      Example::

        import pcaplib
        pcap_reader = pcaplib.Reader('capture.pcap')
        for ts in pcap_reader:
            print(packet)

        (1494608771, 459378, 6, 6, b'\\x00\\x0c)\\xaa4\\xc9')
        (1494608771, 459556, 6, 6, b'\\x00\\x0c)\\xaa4\\xc9')


      .. attribute:: filename

         a filename.

      .. attribute:: version_major

         Major version, currently ``2``.

      .. attribute:: version_minor

         Minor version, currently ``4``.

      .. attribute:: thiszone

         the correction time in seconds between GMT (UTC) and
         the local timezone of the following packet header timestamps.
         In practice, time stamps are always in GMT, so thiszone is always ``0``.

      .. attribute:: sigfigs

         in theory, the accuracy of time stamps in the capture; in practice,
         all tools set it to ``0``.

      .. attribute:: snaplen

         the *snapshot length* for the capture (typically ``65535`` or even more,
         but might be limited by the user).

      .. attribute:: network

          link-layer header type.

      .. attribute:: ts_sec

         the date and time when this packet was captured.
         This value is in *seconds* since January 1, 1970 00:00:00 GMT.

      .. attribute:: ts_usec

         the *microseconds* when this packet was captured,
         as an offset to :attr:`ts_sec`.

      .. attribute:: incl_len

         the number of *bytes* of packet data actually captured and saved in the file.
         This value should never become larger than :attr:`orig_len` or the :attr:`snaplen`
         value of the global header.

      .. attribute:: orig_len

         the length in *bytes* of the packet as it appeared on the network
         when it was captured. If :attr:`incl_len` and :attr:`orig_len` differ,
         the actually saved packet size was limited by snaplen.

   .. autoclass:: Writer


      Construct a Writer which will write in *filename* packets using the PCAP format.

      Example::

         import pcaplib

         pkt_list = [
             (1494608771, 459378, 6, 6, b'\\x00\\x0c)\\xaa4\\xc9'),
             (1494608771, 459556, 6, 6, b'\\x00\\x0c)\\xaa4\\xc9'),
         ]

         pcap_writer = pcaplib.Writer('capture.pcap', pkt_list)
         pcap_writer.writer()


      :param str filename: a filename
      :param iterable packets_iterable: An iterable of 5-tuples,
         each tuple should have the following format
         (``ts_sec``, ``ts_usec``, ``incl_len``, ``orig_len``, ``pkt_data``)
      :param network: the network type, defaults to Ethernet ``Network.EN10B`` or ``1``.

      .. attribute:: packets_iterable.

         An iterable of 5-tuples,

      .. method:: write()

         Iterates over :attr:`packets_iterables` and writes the content in a PCAP file.

Custom Enum
-----------

.. autoclass:: Network(IntEnum)

   An IntEnum representing the network types


Custom Exceptions
-----------------

.. exception:: FileFormatError(Exception)

   Error if the file is not a valid PCAP file