.. toctree::
   :maxdepth: 2

API
===

.. py:module:: fparser
   :synopsis: easy and quick IP netowrk flow sniffing and reconstruction for Python

.. py:class:: FParser

   .. py:function:: __init__(source, is_file = False, flow_timeout = 600, fin_timeout = 30, filter = "ip", snaplen = 100, log_level = syslog.LOG_ERR, tcp_callback = None, udp_callback = None, kill_callback = None)

      An FParser object is a single instance of the parser. It is either
      offline or online. The online (default) variant will keep running
      and consuming flows until the FParser object exits from scope and
      is no longer refrenced from anywhere else or is explicitly
      killed. The offline variant will keep running until the source is
      exhausted. Note that when sniffing on a live interface the python
      process will need the required priviledges (i.e. to be run as root
      or as a user that is allowed to put the interface in promiscous
      mode).

      :param str source: Where to sniff packets from. Can be either an interface name or a file name. If it is a file name is_file must be set to True. Cannot be None.
      
      :param boolean is_file: Does the source argument refer to a file or to an interface name. This determines whether the parser runs online or offline.

      :param int flow_timeout: The timeout in seconds to wait before considering a flow dead (if no FIN is seen)

      :param int fin_timeout: The timeout in seconds to wait before considering a flow dead (FIN is seen)

      :param str filter: BPF to apply to the capture

      :param int snaplen: How many bytes to capture from each packet. Should be large enough to include headers.

      :param syslog.X log_level: How much logging output should the parser generate. The logging output is printed to stdout.

      :param callable tcp_callback: A callable to call when a TCP flow terminates. The callable should take one argument (the flow).
      
      :param callable udp_callback: A callable to call when a UDP flow terminates. Tha callable should take one argument (the flow).

      :param callable kill_callback: A callable to call when the parser is killed. This can happen either explicitly or when the source is exhausted. The callable should take no arguments.        

   .. py:function:: stop()

      Kills the parser. After this method is called the object cannot be used anymore.

   .. py:function:: set_tcp_callback(tcp_callback)

      Sets or resets the TCP flow callback.

      :param callable tcp_callback: A callable to call when a TCP flow terminates. The callable should take one argument (the flow).      

   .. py:function:: set_udp_callback(udp_callback)

      Sets or resets the UDP flow callback.

      :param callable udp_callback: A callable to call when a UDP flow terminates. The callable should take one argument (the flow).
      
   .. py:function:: flow_iter()

      Returns an iterator over the flows currently active in this parser. The iterator can be used in a for loop to iterate over the flows.

   .. py:function:: find_tcp_flow(src_ip, sport, dest_ip, dport)

      Finds a currently active TCP flow with given network and transport layer identifiers. Much faster than iterating over all flows when there are lots of flows.

      :param str src_ip: The source IP address of the flow

      :param int sport: The TCP source port

      :param str dest_ip: The destination IP address of the flow

      :param int dport: The TCP destination port 

   .. py:function:: find_udp_flow(src_ip, sport, dest_ip, dport)

      Finds a currently active UDP flow with given network and transport layer identifiers. Much faster than iterating over all flows when there are lots of flows.

      :param str src_ip: The source IP address of the flow

      :param int sport: The UDP source port

      :param str dest_ip: The destination IP address of the flow

      :param int dport: The UDP destination port 
   
   .. py:function:: get_info()

      Get information about the parser

      :return: an FParserInfo containing information for this parser.   
      
      :rtype: FParserInfo

.. py:class:: FParserInfo

   An immutable class that carries information about a running FParser instance.

   .. py:attribute:: avg_pps

      The average number of packets per second seen by the parser

   .. py:attribute:: tcp_flows

      The number of active TCP flows

   .. py:attribute:: udp_flows

      The number of active UDP flows

   .. py:attribute:: tcp_pkts

      The number of TCP packets stored

   .. py:attribute:: udp_pkts

      The number of UDP packets stored

   .. py:attribute:: time_collecting

      Time spent collecting. A collection is initiated periodically and "reaps" all the flows that are deemed timed out or terminated.