From: Charles-Henri Bruyand <charles-henri.bruyand@open-xchange.com>
Date: Wed, 25 Jul 2018 15:31:56 +0000 (+0200)
Subject: auth: lua records: document DNSRecord objects, and other functions and constants
X-Git-Tag: auth-4.2.0-alpha1~19^2~1
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=2d57897750d495f1bd1ef0c52abbe56f873fb982;p=pdns

auth: lua records: document DNSRecord objects, and other functions and constants
---

diff --git a/docs/lua-records/functions.rst b/docs/lua-records/functions.rst
index da4937f6c..af5e21c8c 100644
--- a/docs/lua-records/functions.rst
+++ b/docs/lua-records/functions.rst
@@ -2,7 +2,7 @@ Preset variables
 ----------------
 
 LUA rules run within the same environment as described in
-:doc:`modes-of-operation`.
+:doc:`../modes-of-operation`.
 
 The Lua snippets can query the following variables:
 
@@ -320,7 +320,7 @@ Helper functions
               country(countries)
 
   Returns true if the ``bestwho`` IP address of the client is within the
-  two letter ISO country code passed, as described in :doc:`backends/geoip`.
+  two letter ISO country code passed, as described in :doc:`../backends/geoip`.
 
   :param string country: A country code like "NL"
   :param [string] countries: A list of country codes
@@ -329,7 +329,7 @@ Helper functions
               continent(continents)
 
   Returns true if the ``bestwho`` IP address of the client is within the
-  continent passed, as described in :doc:`backends/geoip`.
+  continent passed, as described in :doc:`../backends/geoip`.
 
   :param string continent: A continent code like "EU"
   :param [string] continents: A list of continent codes
diff --git a/docs/lua-records/reference/dnsrecord.rst b/docs/lua-records/reference/dnsrecord.rst
new file mode 100644
index 000000000..a3b2b85c8
--- /dev/null
+++ b/docs/lua-records/reference/dnsrecord.rst
@@ -0,0 +1,63 @@
+.. _DNSRecord:
+
+DNSRecord objects
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+A :class:`DNSRecord` object represents a record.
+Creating a ``DNSRecord`` is done with the :func:`newDR`.
+
+.. todo
+   Add a lua example and some useful things to do with that.
+
+Functions and methods of a ``DNSRecord``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. function:: newDR(name, type, ttl, content, place) -> DNSRecord
+
+  Returns a new :class:`DNSRecord` object.
+
+  :param DNSName name: The name to the new record
+  :param string type: The type of the record
+  :param int ttl: The TTL of the record
+  :param string content: The content of the record
+  :param int place: The place where the record is located (as an integer, see :class:`DNSRecord.place`)
+
+.. class:: DNSRecord
+
+  A ``DNSRecord`` object represents a DNS record.
+
+  .. attribute:: DNSRecord.name
+
+    The name of the record. A :class:`DNSName`.
+
+  .. attribute:: DNSRecord.place
+
+    The place where the record is located, you can use the following constants
+
+    - `pdns.place.QUESTION` for the question section
+    - `pdns.place.ANSWER` for the answer section
+    - `pdns.place.AUTHORITY` for the authority section
+    - `pdns.place.ADDITIONAL` for the additional section
+
+  .. attribute:: DNSRecord.ttl
+
+    The TTL of the record
+
+  .. attribute:: DNSRecord.type
+
+    The type of the record (as an integer). Can for example be compared to ``pdns.A``
+
+  .. method:: DNSRecord:getContent() -> string
+
+    Return a string representation of the record content
+
+  .. method:: DNSRecord:getCA() -> ComboAddress
+
+    If the record type is A or AAAA, a :class:`ComboAddress` representing the content is returned, nil otherwise
+
+  .. method:: DNSRecord:changeContent(newcontent)
+
+    Replace the record content with ``newcontent``.
+    The type and class cannot be changed.
+
+    :param str newcontent: The replacing content
diff --git a/docs/lua-records/reference/index.rst b/docs/lua-records/reference/index.rst
index 6cd1b8eaf..dbf23422a 100644
--- a/docs/lua-records/reference/index.rst
+++ b/docs/lua-records/reference/index.rst
@@ -8,5 +8,7 @@ LUA Reference
   dnsheader
   dnsname
   dnsresourcerecord
+  dnsrecord
   netmask
   qtype
+  misc
diff --git a/docs/lua-records/reference/misc.rst b/docs/lua-records/reference/misc.rst
new file mode 100644
index 000000000..247f25049
--- /dev/null
+++ b/docs/lua-records/reference/misc.rst
@@ -0,0 +1,22 @@
+.. _Misc:
+
+Other functions
+^^^^^^^^^^^^^^^
+
+.. function:: pdnslog(message[, loglevel])
+
+  Log the `message` at the daemon level
+
+  :param string message: The message to log
+  :param int loglevel: The urgency level of the message. Defaults to `pdns.loglevels.Warning`
+
+ You can use the following constants as log levels :
+
+   - `pdns.loglevels.Alert`
+   - `pdns.loglevels.Critical`
+   - `pdns.loglevels.Debug`
+   - `pdns.loglevels.Emergency`
+   - `pdns.loglevels.Info`
+   - `pdns.loglevels.Notice`
+   - `pdns.loglevels.Warning`
+   - `pdns.loglevels.Error`