Modular architecture of the library keeps the core tiny and efficient, and provides a state-machine like API for extensions.
.. toctree::
- :maxdepth: 4
+ :maxdepth: 2
build
lib
API reference
=============
-.. doxygengroup:: resolution
- :project: libkresolve
+.. contents::
+ :depth: 1
+ :local:
.. _lib_api_rplan:
+Name resolution
+---------------
+
+.. doxygengroup:: resolution
+ :project: libkresolve
+
.. doxygengroup:: rplan
:project: libkresolve
+.. _lib_api_cache:
+
+Cache
+-----
+
.. doxygengroup:: cache
:project: libkresolve
+.. _lib_api_nameservers:
+
+Nameservers
+-----------
+
.. doxygengroup:: nameservers
:project: libkresolve
.. _lib_api_modules:
+Modules
+-------
+
.. doxygengroup:: modules
:project: libkresolve
+Utilities
+---------
+
.. doxygengroup:: utils
:project: libkresolve
:local:
The library as described provides basic services for name resolution, which should cover the usage.
-The following part is for those who are planning to hack on the library or develop modules, to give
-you an idea about the API and the library layout.
-
-Name resolution
----------------
-
-.. _lib_rplan:
-
-Resolution plan
----------------
-
-.. _lib_cache:
-
-Cache
------
-
-.. _lib_nameservers:
-
-Nameservers
------------
-
-Utilities
-~~~~~~~~~
-
-.. warning:: Work in progress.
Resolving a name
----------------
The library offers following services:
-- :ref:`Cache <lib_cache>` - MVCC cache interface for retrieving/storing resource records.
-- :ref:`Resolution plan <lib_rplan>` - Query resolution plan, a list of partial queries (with hierarchy) sent in order to satisfy original query. This contains information about the queries, nameserver choice, timing information, answer and its class.
-- :ref:`Nameservers <lib_nameservers>` - Reputation database of nameservers, this serves as an aid for nameserver choice.
+- :ref:`Cache <lib_api_cache>` - MVCC cache interface for retrieving/storing resource records.
+- :ref:`Resolution plan <lib_api_rplan>` - Query resolution plan, a list of partial queries (with hierarchy) sent in order to satisfy original query. This contains information about the queries, nameserver choice, timing information, answer and its class.
+- :ref:`Nameservers <lib_api_nameservers>` - Reputation database of nameservers, this serves as an aid for nameserver choice.
A processing layer is going to be called by the query resolution driver for each query,
so you're going to work with :ref:`struct kr_layer_param <lib_api_rplan>` as your per-query context. This structure contains pointers to
doesn't allow custom allocation scheme. BSD-licensed (or compatible) code is allowed here,
as long as it comes with a test case in `tests/test_generics.c`.
-Data structures
-~~~~~~~~~~~~~~~
+* array_ - a set of simple macros to make working with dynamic arrays easier.
+* map_ - a `Crit-bit tree`_ key-value map implementation (public domain) that comes with tests.
+* set_ - set abstraction implemented on top of ``map``.
+* pack_ - length-prefixed list of objects (i.e. array-list).
-* ``array`` - a set of simple macros to make working with dynamic arrays easier.
-* ``set`` - a `Crit-bit tree`_ simple implementation (public domain) that comes with tests.
-* ``map`` - key-value map implemented on top of ``set``.
-* ``pack`` - length-prefixed list of objects (i.e. array-list).
+array
+~~~~~
-API reference and examples
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. doxygenfile:: array.h
+ :project: libkresolve
+
+map
+~~~
+
+.. doxygenfile:: map.h
+ :project: libkresolve
+
+set
+~~~
+
+.. doxygenfile:: set.h
+ :project: libkresolve
+
+pack
+~~~~
-.. doxygengroup:: generics
+.. doxygenfile:: pack.h
:project: libkresolve
.. _`Crit-bit tree`: http://cr.yp.to/critbit.html
*/
/**
- * Generics - simple dynamic array.
*
- * \note The C has no generics, so it is implemented mostly using macros.
+ * @file array.h
+ * @brief A set of simple macros to make working with dynamic arrays easier.
+ *
+ * @note The C has no generics, so it is implemented mostly using macros.
* Be aware of that, as direct usage of the macros in the evaluating macros
- * may lead to different expectations, i.e.
+ * may lead to different expectations:
*
+ * # Undefined behaviour
* MIN(array_push(arr, val), other)
*
- * May evaluate the code twice, leading to unexpected behaviour.
- * This is a price to pay for absence of proper generics.
+ * May evaluate the code twice, leading to unexpected behaviour.
+ * This is a price to pay for the absence of proper generics.
*
- * Example usage:
+ * Example usage:
*
* array_t(const char*) arr;
* array_init(arr);
*/
/**
- * Generics - A Crit-bit tree 'map' implementation.
*
- * @warning If the user provides a custom allocator, it must return addresses aligned to 2B boundary.
+ * @file map.h
+ * @brief A Crit-bit tree key-value map implementation.
*
- * Example usage:
+ * @warning If the user provides a custom allocator, it must return addresses aligned to 2B boundary.
+ *
+ * Example usage:
*
* map_t map = map_make();
*
*/
/**
- * Generics - array of lenght-prefixed packed objects
+ * @file pack.h
+ * @brief A length-prefixed list of objects, also an array list.
*
* Each object is prefixed by item length, unlike array this structure
* permits variable-length data. It is also equivallent to forward-only list
* backed by an array.
*
- * @note Maximum object size is 2^16 bytes, @see pack_objlen_t
+ * @note Maximum object size is 2^16 bytes, see ::pack_objlen_t
*
* Example usage:
*
- * pack_t pack;
- * pack_init(pack);
+ * pack_t pack;
+ * pack_init(pack);
*
- * // Reserve 2 objects, 6 bytes total
- * pack_reserve(pack, 2, 4 + 2);
- *
- * // Push 2 objects
- * pack_obj_push(pack, U8("jedi"), 4)
- * pack_obj_push(pack, U8("\xbe\xef"), 2);
+ * // Reserve 2 objects, 6 bytes total
+ * pack_reserve(pack, 2, 4 + 2);
+ *
+ * // Push 2 objects
+ * pack_obj_push(pack, U8("jedi"), 4)
+ * pack_obj_push(pack, U8("\xbe\xef"), 2);
*
- * // Iterate length-value pairs
- * uint8_t *it = pack_head(pack);
- * while (it != pack_tail(pack)) {
- * uint8_t *val = pack_obj_val(it);
- * it = pack_obj_next(it);
- * }
+ * // Iterate length-value pairs
+ * uint8_t *it = pack_head(pack);
+ * while (it != pack_tail(pack)) {
+ * uint8_t *val = pack_obj_val(it);
+ * it = pack_obj_next(it);
+ * }
*
- * pack_clear(pack);
+ * pack_clear(pack);
*
* \addtogroup generics
* @{
#include <string.h>
#include "array.h"
+#ifdef __cplusplus
+extern "C" {
+#endif
+
/** Packed object length type. */
typedef uint16_t pack_objlen_t;
memcpy(endp + sizeof(len), obj, len);
pack->len += packed_len;
return 0;
-}
\ No newline at end of file
+}
+
+#ifdef __cplusplus
+}
+#endif
+
+/** @} */
+/* Copyright (C) 2015 CZ.NIC, z.s.p.o. <knot-dns@labs.nic.cz>
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program 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 General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see <http://www.gnu.org/licenses/>.
+ */
+
/**
- * Generics - A Crit-bit set implementation.
+ * @file set.h
+ * @brief A set abstraction implemented on top of map.
*
- * @note The API is based on @fn map.h, see it for more examples.
+ * @note The API is based on map.h, see it for more examples.
*
- * Example usage:
+ * Example usage:
*
* set_t set = set_make();
*
}
#endif
-/** @} */
\ No newline at end of file
+/** @} */
#include "lib/cache.h"
#include "lib/zonecut.h"
-/* Query flags */
+/** Query flags */
enum kr_query_flag {
QUERY_NO_MINIMIZE = 1 << 0, /**< Don't minimize QNAME. */
QUERY_TCP = 1 << 1 /**< Use TCP for this query. */
projects / thirdparty / knot-resolver.git / commitdiff
