From: Francis Dupont <fdupont@isc.org>
Date: Mon, 14 Jan 2019 15:41:15 +0000 (+0100)
Subject: [313-return-a-list-of-all-reservations-by-subnet-id] Updated doc
X-Git-Tag: 429-Updated-StampedValue-to-support-reals_base~82
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6244106c82a77a488e802539ad72b9845c6694f1;p=thirdparty%2Fkea.git

[313-return-a-list-of-all-reservations-by-subnet-id] Updated doc
---

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 95f03b1849..192f64d44c 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -107,7 +107,7 @@ EXTRA_DIST += api/network6-get.json api/network6-list.json
 EXTRA_DIST += api/network6-subnet-add.json api/network6-subnet-del.json
 EXTRA_DIST += api/reservation-add.json api/reservation-del.json
 EXTRA_DIST += api/reservation-get.json api/reservation-get-all.json
-EXTRA_DIST += api/shutdown.json
+EXTRA_DIST += api/reservation-get-page.json api/shutdown.json
 EXTRA_DIST += api/statistic-get-all.json api/statistic-get.json
 EXTRA_DIST += api/statistic-remove-all.json api/statistic-remove.json
 EXTRA_DIST += api/statistic-reset-all.json api/statistic-reset.json
diff --git a/doc/api/reservation-get-page.json b/doc/api/reservation-get-page.json
new file mode 100644
index 0000000000..fb74bdc4f1
--- /dev/null
+++ b/doc/api/reservation-get-page.json
@@ -0,0 +1,18 @@
+{
+    "name": "reservation-get-page",
+    "brief": "Retrieve host reservations for a specified subnet by page.",
+    "support": [ "kea-dhcp4", "kea-dhcp6" ],
+    "hook": "host_cmds",
+    "avail": "1.6.0",
+
+    "cmd-syntax": "{
+    \"command\": \"reservation-get-page\",
+    \"arguments\": {
+        \"subnet-id\": <integer>,
+        \"limit\": <integer>,
+        \"source-index\": <integer>,
+        \"from\": <integer>
+    }
+}",
+    "cmd-comment": "the subnet id and the page size limit are mandatory. The source index and from host id are optional and default to 0."
+}
diff --git a/doc/docgen/cmds-list b/doc/docgen/cmds-list
index adbdffdb03..9aa4be6a80 100644
--- a/doc/docgen/cmds-list
+++ b/doc/docgen/cmds-list
@@ -52,6 +52,7 @@ reservation-add
 reservation-del
 reservation-get
 reservation-get-all
+reservation-get-page
 shutdown
 stat-lease4-get
 stat-lease6-get
diff --git a/doc/guide/api.xml b/doc/guide/api.xml
index e20fa59f6b..fbc1aa9b8f 100644
--- a/doc/guide/api.xml
+++ b/doc/guide/api.xml
@@ -64,6 +64,7 @@
 , <command><link linkend="ref-reservation-del">reservation-del</link></command>
 , <command><link linkend="ref-reservation-get">reservation-get</link></command>
 , <command><link linkend="ref-reservation-get-all">reservation-get-all</link></command>
+, <command><link linkend="ref-reservation-get-page">reservation-get-page</link></command>
 , <command><link linkend="ref-shutdown">shutdown</link></command>
 , <command><link linkend="ref-stat-lease4-get">stat-lease4-get</link></command>
 , <command><link linkend="ref-stat-lease6-get">stat-lease6-get</link></command>
@@ -145,6 +146,7 @@
 , <command><link linkend="ref-reservation-del">reservation-del</link></command>
 , <command><link linkend="ref-reservation-get">reservation-get</link></command>
 , <command><link linkend="ref-reservation-get-all">reservation-get-all</link></command>
+, <command><link linkend="ref-reservation-get-page">reservation-get-page</link></command>
 , <command><link linkend="ref-shutdown">shutdown</link></command>
 , <command><link linkend="ref-stat-lease4-get">stat-lease4-get</link></command>
 , <command><link linkend="ref-statistic-get">statistic-get</link></command>
@@ -201,6 +203,7 @@
 , <command><link linkend="ref-reservation-del">reservation-del</link></command>
 , <command><link linkend="ref-reservation-get">reservation-get</link></command>
 , <command><link linkend="ref-reservation-get-all">reservation-get-all</link></command>
+, <command><link linkend="ref-reservation-get-page">reservation-get-page</link></command>
 , <command><link linkend="ref-shutdown">shutdown</link></command>
 , <command><link linkend="ref-stat-lease6-get">stat-lease6-get</link></command>
 , <command><link linkend="ref-statistic-get">statistic-get</link></command>
@@ -237,6 +240,7 @@
 , <command><link linkend="ref-reservation-del">reservation-del</link></command>
 , <command><link linkend="ref-reservation-get">reservation-get</link></command>
 , <command><link linkend="ref-reservation-get-all">reservation-get-all</link></command>
+, <command><link linkend="ref-reservation-get-page">reservation-get-page</link></command>
 .</para>
 <para xml:id="commands-lease_cmds-lib">Commands supported by lease_cmds hook library: <command><link linkend="ref-lease4-add">lease4-add</link></command>
 , <command><link linkend="ref-lease4-del">lease4-del</link></command>
@@ -2570,6 +2574,71 @@ The reservation-get-all command may result in very large responses.</para>
 </section>
 <!-- end of reservation-get-all -->
 
+<!-- start of reservation-get-page -->
+<section xml:id="reference-reservation-get-page">
+<title>reservation-get reference</title>
+<para xml:id="ref-reservation-get-page"><command>reservation-get-page</command> - Retrieve all host reservations for a specified subnet by pages.</para>
+
+<para>Supported by: <command><link linkend="commands-kea-dhcp4">kea-dhcp4</link></command>, <command><link linkend="commands-kea-dhcp6">kea-dhcp6</link></command></para>
+
+<para>Availability: 1.6.0 (<link linkend="commands-host_cmds-lib">host_cmds</link>  hook)</para>
+
+<para>Description and examples: See <xref linkend="command-reservation-get-page"/></para>
+
+<para>Command syntax:
+  <screen>{
+    "command": "reservation-get-page",
+    "arguments": {
+        "subnet-id": &lt;integer&gt;,
+        "limit": &lt;integer&gt;,
+        "source-index": &lt;integer&gt;,
+        "from": &lt;integer&gt;
+    }
+}</screen>
+Returned host reservations are from the specified subnet. Page size is
+limited by the limit parameter. Start of the page is given by the optional
+source index (default 0 i.e. configuration file) and from host id (default
+0).
+</para>
+
+<para>Response syntax:
+  <screen>{
+    "result": &lt;integer&gt;,
+    "text": &lt;string&gt;,
+    "arguments": {
+        "source-index": &lt;string&gt;,
+        "count": &lt;string&gt;,
+        "next": &lt;integer&gt;,
+        "hosts": [
+            {
+                "boot-file-name": &lt;string&gt;,
+                "comment": &lt;string&gt;
+                "client-id": &lt;string&gt;,
+                "circuit-id": &lt;string&gt;,
+                "duid": &lt;string&gt;,
+                "flex-id": &lt;string&gt;,
+                "ip-address": &lt;string (IPv4 address)&gt;,
+                "ip-addresses": [ &lt;comma separated strings&gt; ],
+                "hw-address": &lt;string&gt;,
+                "hostname": &lt;string&gt;,
+                "next-server": &lt;string (IPv4 address)&gt;,
+                "option-data-list": [ &lt;comma separated structures defining options&gt; ],
+                "prefixes": [ &lt;comma separated IPv6 prefixes&gt; ],
+                "reservation-client-classes": [ &lt;comma separated strings&gt; ],
+                "server-hostname": &lt;string&gt;,
+                "subnet-id": &lt;integer&gt;,
+                "user-context": &lt;any valid JSON&gt;,
+            },
+            ...
+        ]
+    }
+}</screen>
+The source index and the next host id should be used getting the next page.
+After the last page the result is 3 (empty).
+</para>
+</section>
+<!-- end of reservation-get-page -->
+
 <!-- start of shutdown -->
 <section xml:id="reference-shutdown">
 <title>shutdown reference</title>
diff --git a/doc/guide/hooks.xml b/doc/guide/hooks.xml
index bc4bdd67cc..582d25e9cb 100644
--- a/doc/guide/hooks.xml
+++ b/doc/guide/hooks.xml
@@ -1421,8 +1421,9 @@ $
           Currently four commands are supported: reservation-add (which adds
           new host reservation), reservation-get (which returns existing
           reservation if specified criteria are matched), reservation-get-all
-          (which returns all reservations in a specified subnet) and
-          reservation-del
+          (which returns all reservations in a specified subnet),
+          reservation-get-page (variant of reservation-get-all which returns
+          all reservations in a specified subnet by pages) and reservation-del
           (which attempts to delete a reservation matching specified
           criteria). To use commands that change the reservation information
           (currently these are reservation-add and reservation-del, but this
@@ -1664,7 +1665,27 @@ An example result returned when the query was malformed:<screen>
           <para>The response returned by <command>reservation-get-all</command>
           can be very long.
           </para>
-       </section>
+        </section>
+
+        <section xml:id="command-reservation-get-page">
+          <title>reservation-get-page command</title>
+          <para><command>reservation-get-page</command> can be used to
+          query the host database and retrieve all reservations in a
+          specified subnet by pages. This command uses parameters providing the
+          mandatory subnet-id. Use a value of zero (0) to fetch global
+          reservations. The second mandatory parameter is the page size limit.
+          Optional source-index and from host id, both defaulting to 0, are
+          uses to chain page queries.
+          </para>
+
+          <!-- Add example -->
+
+          <para>The first page is queried without source-index and from,
+          for next pages source-index and from should be set using
+          the preceeding result source-index and next. After the last page
+          the result is empty (code 3).
+          </para>
+        </section>
 
         <section xml:id="command-reservation-del">
           <title>reservation-del command</title>