.. include:: header.rst

`home`__

__ reference.html

.. contents:: Table of contents
  :depth: 2
  :backlinks: none

.. raw:: html

	<a name="ip_filter"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+ip_filter&labels=documentation&body=Documentation+under+heading+%22class+ip_filter%22+could+be+improved">report issue</a>]</span>



ip_filter
---------

Declared in "`libtorrent/ip_filter.hpp`__"


__ include/libtorrent/ip_filter.hpp

The ``ip_filter`` class is a set of rules that uniquely categorizes all
ip addresses as allowed or disallowed. The default constructor creates
a single rule that allows all addresses (0.0.0.0 - 255.255.255.255 for
the IPv4 range, and the equivalent range covering all addresses for the
IPv6 range).

A default constructed `ip_filter`__ does not filter any address.


__ reference-Filter.html#ip_filter


.. parsed-literal::
	

	struct ip_filter
	{
	   ip_filter& **operator=** (ip\_filter&&);
	   **ip_filter** (ip\_filter&&);
	   **ip_filter** (ip\_filter const&);
	   **ip_filter** ();
	   ip_filter& **operator=** (ip\_filter const&);
	   **~ip_filter** ();
	   bool **empty** () const;
	   void **add_rule** (address const& first, address const& last, std\:\:uint32\_t flags);
	   std::uint32_t **access** (address const& addr) const;
	   filter_tuple_t **export_filter** () const;
	
	   enum access_flags
	   {
	      blocked,
	   };
	};

.. raw:: html

	<a name="empty()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:ip_filter%3A%3A%5Bempty%28%29%5D&labels=documentation&body=Documentation+under+heading+%22ip_filter%3A%3A%5Bempty%28%29%5D%22+could+be+improved">report issue</a>]</span>



empty()
.......

.. parsed-literal::
	
	bool **empty** () const;
	

returns true if the filter does not contain any rules



.. raw:: html

	<a name="add_rule()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:ip_filter%3A%3A%5Badd_rule%28%29%5D&labels=documentation&body=Documentation+under+heading+%22ip_filter%3A%3A%5Badd_rule%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_rule()
..........

.. parsed-literal::
	
	void **add_rule** (address const& first, address const& last, std\:\:uint32\_t flags);
	

Adds a rule to the filter. ``first`` and ``last`` defines a range of
ip addresses that will be marked with the given flags. The ``flags``
can currently be 0, which means allowed, or ``ip_filter::blocked``, which
means disallowed.

precondition:
``first.is_v4() == last.is_v4() && first.is_v6() == last.is_v6()``

postcondition:
``access(x) == flags`` for every ``x`` in the range [``first``, ``last``]

This means that in a case of overlapping ranges, the last one applied takes
precedence.



.. raw:: html

	<a name="access()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:ip_filter%3A%3A%5Baccess%28%29%5D&labels=documentation&body=Documentation+under+heading+%22ip_filter%3A%3A%5Baccess%28%29%5D%22+could+be+improved">report issue</a>]</span>



access()
........

.. parsed-literal::
	
	std::uint32_t **access** (address const& addr) const;
	

Returns the access permissions for the given address (``addr``). The permission
can currently be 0 or ``ip_filter::blocked``. The complexity of this operation
is O(``log`` n), where n is the minimum number of non-overlapping ranges to describe
the current filter.



.. raw:: html

	<a name="export_filter()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:ip_filter%3A%3A%5Bexport_filter%28%29%5D&labels=documentation&body=Documentation+under+heading+%22ip_filter%3A%3A%5Bexport_filter%28%29%5D%22+could+be+improved">report issue</a>]</span>



export_filter()
...............

.. parsed-literal::
	
	filter_tuple_t **export_filter** () const;
	

This function will return the current state of the filter in the minimum number of
ranges possible. They are sorted from ranges in low addresses to high addresses. Each
`entry`__ in the returned vector is a range with the access control specified in its
``flags`` field.

The return value is a tuple containing two range-lists. One for IPv4 addresses
and one for IPv6 addresses.


__ reference-Bencoding.html#entry

.. raw:: html

	<a name="access_flags"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+access_flags&labels=documentation&body=Documentation+under+heading+%22enum+access_flags%22+could+be+improved">report issue</a>]</span>



enum access_flags
.................

Declared in "`libtorrent/ip_filter.hpp`__"


__ include/libtorrent/ip_filter.hpp

+---------+-------+----------------------------------------------------------+
| name    | value | description                                              |
+=========+=======+==========================================================+
| blocked | 1     | indicates that IPs in this range should not be connected |
|         |       | to nor accepted as incoming connections                  |
|         |       |                                                          |
+---------+-------+----------------------------------------------------------+



.. raw:: html

	<a name="port_filter"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:class+port_filter&labels=documentation&body=Documentation+under+heading+%22class+port_filter%22+could+be+improved">report issue</a>]</span>



port_filter
-----------

Declared in "`libtorrent/ip_filter.hpp`__"


__ include/libtorrent/ip_filter.hpp

the port filter maps non-overlapping port ranges to flags. This
is primarily used to indicate whether a range of ports should
be connected to or not. The default is to have the full port
range (0-65535) set to flag 0.




.. parsed-literal::
	

	class port_filter
	{
	   **port_filter** ();
	   **~port_filter** ();
	   **port_filter** (port\_filter&&);
	   port_filter& **operator=** (port\_filter const&);
	   port_filter& **operator=** (port\_filter&&);
	   **port_filter** (port\_filter const&);
	   void **add_rule** (std\:\:uint16\_t first, std\:\:uint16\_t last, std\:\:uint32\_t flags);
	   std::uint32_t **access** (std\:\:uint16\_t port) const;
	
	   enum access_flags
	   {
	      blocked,
	   };
	};

.. raw:: html

	<a name="add_rule()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:port_filter%3A%3A%5Badd_rule%28%29%5D&labels=documentation&body=Documentation+under+heading+%22port_filter%3A%3A%5Badd_rule%28%29%5D%22+could+be+improved">report issue</a>]</span>



add_rule()
..........

.. parsed-literal::
	
	void **add_rule** (std\:\:uint16\_t first, std\:\:uint16\_t last, std\:\:uint32\_t flags);
	

set the flags for the specified port range (``first``, ``last``) to
``flags`` overwriting any existing rule for those ports. The range
is inclusive, i.e. the port ``last`` also has the flag set on it.



.. raw:: html

	<a name="access()"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:port_filter%3A%3A%5Baccess%28%29%5D&labels=documentation&body=Documentation+under+heading+%22port_filter%3A%3A%5Baccess%28%29%5D%22+could+be+improved">report issue</a>]</span>



access()
........

.. parsed-literal::
	
	std::uint32_t **access** (std\:\:uint16\_t port) const;
	

test the specified port (``port``) for whether it is blocked
or not. The returned value is the flags set for this port.
see `access_flags`__.


__ reference-Filter.html#access_flags

.. raw:: html

	<a name="access_flags"></a>

.. raw:: html

	<span class="report-issue">[<a href="http://github.com/arvidn/libtorrent/issues/new?title=docs:enum+access_flags&labels=documentation&body=Documentation+under+heading+%22enum+access_flags%22+could+be+improved">report issue</a>]</span>



enum access_flags
.................

Declared in "`libtorrent/ip_filter.hpp`__"


__ include/libtorrent/ip_filter.hpp

+---------+-------+---------------------------------------------------+
| name    | value | description                                       |
+=========+=======+===================================================+
| blocked | 1     | this flag indicates that destination ports in the |
|         |       | range should not be connected to                  |
|         |       |                                                   |
+---------+-------+---------------------------------------------------+





.. _`BEP 3`: https://www.bittorrent.org/beps/bep_0003.html
.. _`BEP 17`: https://www.bittorrent.org/beps/bep_0017.html
.. _extensions: manual-ref.html#extensions
.. _`BEP 52`: https://www.bittorrent.org/beps/bep_0052.html
.. _`BEP 19`: https://www.bittorrent.org/beps/bep_0019.html
.. _`BEP 38`: https://www.bittorrent.org/beps/bep_0038.html
.. _`rate based choking`: manual-ref.html#rate-based-choking
.. _`BEP 42`: https://www.bittorrent.org/beps/bep_0042.html
