                              Name Lookup Interface
                              =====================
Overview
--------
Internet hosts are generally identified using a 4 byte numeric IP address, however since such numbers are not easily rememered by humans, so-called domain
name servers exist, which map textual names to IP addresses and back. Rabbit
provides scripts with the ability to convert between IP addresses and hostnames
in a non-blocking way.


Technical details
-----------------
   A script wishing to convert a hostname to an IP address calls the start_lookup command which returns a lookup handle. Rabbit then proceeds with
an attempt to resolve the name. Once the attempt is completed the result, even
if it is a failure, is reported to the script via the lookup_complete entry
point.
   The procedure for a reverse lookup (IP address to hostname) almost identical.
In this case the script calls the start_reverse_lookup command and the result is
reported via the reverse_lookup_complete entry point.


Commands
--------

int start_lookup(string address, int number)

   * Parameters:

       address    - The textual host name to be looked up (e.g. toth.org.uk)
       number     - The entry in the host's list of IP addresses to return
                    starting with 0.

   * Returns: Lookup handle

   begins a lookup of a host's IP address. Once complete the script is notified via the lookup_complete entry point.



int start_reverse_lookup(int address; int number)

   * Parameters:

       address    - The numeric IP address in network byte order
       number     - The entry in the host's list of textual to return starting
                    with 0.

   * Returns: Lookup handle

   begins a lookup of a host's name. Once complete the script is notified via
the reverse_lookup_complete entry point.


void abort_lookup(int handle)

   * Parameters:

       handle     - The handle of the lookup to abort

   terminates a lookup that has not yet been completed. This call aborts both
regular and reverse lookups.


Entry Points
------------

void lookup_complete(int handle; int result; int ip)

   * Parameters:

       handle     - The lookup handle returned by start_lookup.
       result     - The "result" of the lookup attempt, a reason code indicating
                    success or cause of failure, *not* the ip address.
                    Possible result are:
                      1 - Success.
                      2 - Unable to access the nameserver.
                      3 - The name corresponds to fewer IP addresses than the
                          entry requested.
                      4 - The hostname is unknown.
       ip         - The host's IP address, only valid if result=1.

   is called following a script's call to start_lookup either to report a
successfully obtained IP address or a reason for failing to do so.
   This entry point will not be called in response to a call to
start_reverse_lookup, which has its own corresponding entry point (see below).



void reverse_lookup_complete(int handle; int result; string name; int ip)

   * Parameters:

       handle     - The lookup handle returned by start_reverse_lookup.
       result     - As for lookup_complete (see above).
       name       - The name corresponding to the the resolved IP address
                    (null if result != 1).
       ip         - The host's IP address as passed to start_reverse_lookup.

   is called following a script's call to start_reverse_lookup either to report
a successfully obtained IP address or a reason for failing to do so.
