More low-level procedures.

doc/latex/dns.tex

@@ -71,7 +71,7 @@ the library. The supertype of these conditions is \exi{dns-error}.
 
 \section{High-level Interface}
 \def\ipaddr{\textnormal{IP-address\xspace}}
-\def\fqdn{\textnormal{FQDN\xspace}}
+\def\fqdn{\textnormal{FQDN}\xspace}
 
 The library uses an internal store to cache data obtained from DNS
 servers. All procedures take a boolean flag \var{use-cache?} that
@@ -87,7 +87,7 @@ The library is further capable of parsing the contents of
 \texttt{/etc/resolv.conf} (see Section~\ref{sec:dns-rc}). The
 nameservers listed there are the default value for the optional
 argument \var{nameserver list} which many procedures of the library
-possess.
+possess. \var{nameserver} is either a \ipaddr or a dotted IP string.
 
 \defun{dns-lookup-ip}{\fqdn [nameserver list][use-cache?]}{\fqdn}
 \begin{desc}
@@ -134,17 +134,42 @@ possess.
 \defun{host-fqdn} {name/socket-address [nameserver list][use-cache?]}{\fqdn}
 \defunx{system-fqdn}{[nameserver list][use-cache?]}{\fqdn}
 \begin{desc}
-  \ex{host-fqdn} returns the fully qualified domain name (FQDN) for its
+  \ex{host-fqdn} returns the fully qualified domain name (FQDN) for
-    argument which can be either a unqualified host name or a socket
+  its argument which can be either a unqualified host name or a socket
-    address.  The procedure \ex{system-fqdn} returns the FQDN of the
+  address.  The procedure \ex{system-fqdn} returns the FQDN of the
-    current host.\oops{optional arguments not implemented yet}
+  current host. These procedures use a list of domain names obtained
+  from \texttt{/etc/resolv.conf} to the generate FQDNs and try to
+  resolve these FQDNs.\oops{optional arguments not implemented yet}
 \end{desc}
 
 \section{Low-level Interface}
 
-\defun{dns-lookup}{\fqdn/\ipaddr type [nameserver list][use-cache?]}{dns-message}
+This section describes a set of data structures and procedures which
+directly correspond to the data flow of the DNS protocol. The central
+entity is a \var{message}, the abstraction of the packet sent to the
+server or received from the server (The DNS protocol uses the same
+data format for both directions). A \var{dns-message} encapsulates the
+query message sent to the server, the response message received from
+the server, and some additional information the library gathered while
+generating the \var{dns-message}.
+
+\defunx{dns-get-information}{message protocol answer-okay? [nameserver
+  list][use-cache?]}{dns-message}
 \begin{desc}
-  This is the most general way to submit a DNS query. The return value
+  Most general way to submit a DNS query. The message is sent to the
+  name servers via \var{protocol} which can be either \ex{'tcp} or
+  {'udp}. After receiving the reply, \ex{dns-get-information} applies
+  the predicate \var{answer-okay?} to the message. If it returns
+  \sharpf and the answer is not authoritative additional name servers
+  sent with the reply are checked until an authoritative answer is
+  found. If the predicate returns \sharpf but the answer is
+  authoritative a \var{bad-address} condition is signalled.
+  \oops{order of parameters differs in implementation}
+\end{desc}
+
+\defun{dns-lookup}{\fqdn{}/\ipaddr type [nameserver list][use-cache?]}{dns-message}
+\begin{desc}
+  Convenient shortcut to submit a DNS query. The return value
   is a \ex{dns-message} structure:\oops{optional arguments not implemented yet}
 \end{desc}
 
@@ -183,6 +208,18 @@ possess.
   returns the actual data sent over the network.
 \end{desc}
 
+\defun{make-query-message header}{header question [questions]}{message}
+\begin{desc}
+  The procedure generates a message the supplied questions,
+  \var{header}, and the standard message values for queries.
+\end{desc}
+\defun{make-simple-query-message}{name type class}{message}
+\begin{desc}
+  This simplified constructor generates a message with one question
+  which is built from the parameters, and the standard header flags
+  for queries and the standard message values for queries.
+\end{desc}
+
 \defun{header?}{thing}{\boolean}
 \defunx{header-id}{header}{number}
 \defunx{header-flags}{header}{flags}
@@ -220,8 +257,7 @@ possess.
   A question sent to the DNS server.
 \end{desc}
 The type and class of the question and answer are elements of
-enumerated types: \textbf{class doesn't start at 0}
+enumerated types:
-
 \dfn{message-class}{class-name}{message-class}{syntax}
 \defunx{message-class?}{thing}{\boolean}
 \defunx{message-class-name}{message-class}{symbol}
@@ -332,7 +368,7 @@ The possible names for the classes are:
 \begin{desc}
   A zone of authority resource record. 
 \end{desc}
-The protocol specifies other possiple values for the \texttt{rr-data}
+The protocol specifies other possible values for the \texttt{rr-data}
 field but we where no able to find test cases for them.
 
 
@@ -381,7 +417,7 @@ field but we where no able to find test cases for them.
 \begin{desc}
   Returns the contents of \texttt{/etc/resolv.conv} as an alist with
   the possible keys \texttt{nameserver}, \texttt{domain},
-  \texttt{search}, \texttt{sortlist}, \texttt{options}.
+  \texttt{search}, \texttt{sortlist} and \texttt{options}.
   
   Note that the library caches the contents of
   \texttt{/etc/resolv.conv} and \ex{resolv.conf} only really opens the
@@ -404,7 +440,7 @@ field but we where no able to find test cases for them.
   \texttt{/etc/resolv.conf} does not contain a \texttt{nameserver}
   entry.
 \end{desc}
-\defun{domains-for-search}{}{\str list}
+\defun{domains-for-search}{}{\str{} list}
 \begin{desc}
   Parses \texttt{/etc/resolv.conf} and extracts the domains specified
   by the \texttt{search} keyword.