..
    Copyright (c) 2022, 2023, Panagiotis Tsirigotis
    
    This file is part of linuxnet-iptables.
    
    linuxnet-iptables is free software: you can redistribute it and/or
    modify it under the terms of version 3 of the GNU Affero General Public
    License as published by the Free Software Foundation.
    
    linuxnet-iptables is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
    or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
    License for more details.
    
    You should have received a copy of the GNU Affero General
    Public License along with linuxnet-iptables. If not, see
    <https://www.gnu.org/licenses/>.

.. _match:

.. currentmodule:: linuxnet.iptables

Matches
=======

The programmatic interface to packet matching is based on the concept
of a :class:`Match` object that provides methods returning
:class:`Criterion` objects which in turn allow for equality (and
inequality) testing against a stored value.

In the following example, :class:`PacketMatch` (a subclass of
:class:`Match`) provides matching against packet attributes
such as protocol, source address, etc.

::

    m = PacketMatch()
    m.protocol().equals('udp')

The :meth:`protocol` method returns a
ProtocolCriterion` object which stores the value that
we want to compare against (``udp`` in this case).

A :class:`Match` object may have multiple criteria; such criteria
are specific to the :class:`Match` subclass.

Continuing the example::

    a = IPv4Network('1.2.3.4/32')
    mcast = IPV4Network('224.0.0.0/4')
    m.source_address().equals(a).dest_address().not_equals(mcast)

The :meth:`source_address` method returns a
:class:`SourceAddressCriterion` object, while
the :meth:`dest_address` method returns a
:class:`DestAddressCriterion` object.
The resulting :class:`Match` object now matches UDP packets with
a source address of 1.2.3.4 and a destination address that is not
a multicast address.

-------

The :class:`Match` class is the parent class of all match-related classes.
No objects of this class are instantiated.

The :class:`Criterion` class is the parent class of all classes implementing
match-specific criteria.
No objects of this class are instantiated.
Objects of subclasses of :class:`Criterion` are never directly instantiated
by the user; they are instantiated
as needed by the :class:`Match` subclasses.

:class:`MatchNone` is a special subclass of :class:`Match` that is used
to indicate the absence of a match.

-------

.. autoclass:: Match
    :members:

-------

.. autoclass:: Criterion
    :members:

-------

.. autoclass:: MatchNone
    :members:
    :inherited-members: Match


.. toctree::
    :maxdepth: 2
    :hidden:
    :glob:

    matches/*