InetSuite DNS resolver module SWI interface

Environment variables used

Inet$Resolvers	SPACE separated list of dotted IP addresses of servers
Inet$Hostname	Used by gethostname() to read local host name
Inet$LocalDomain	Overrides local domain (normally taken from Inet$Hostname)
Inet$SearchDomains	SPACE separated list of IP domain names to search on
Inet$ResolverRetries	Number of retries when lookups fail
Inet$ResolverDelay	Delay in seconds between retry attempts

Resolver module

The Resolver relocatable module provides the following SWI calls for use by network applications wishing to perform DNS/Hosts file name lookups;

Resolver_GetHostByName (SWI 0x46000)

Lookup a hostname string (single-tasking). On entry

R1	= pointer to host name string, 0 terminated

On exit

R0	= errno integer value if V flag is clear, or
	= error block pointer if V flag is set
R1	= pointer to completed 'hostent' struct if successful,
	= 0 if failed

All other registers preserved on exit Use This SWI is provided primarily for backwards compatibility, since new network applications can use the more flexible _GetHost SWI as described below.

However the main use of this SWI is by the Acorn Internet module (2.10 or later) from the C language gethostbyname() function call. The exact algorithm followed is that on any hostname lookup, this SWI is called, and if no error is returned, then the hostent ptr returned is used by the Internet module. If an error is returned, the Internet module uses its own (broken) /etc/hosts file lookup code.

The hostent struct has the following, Net-BSD standard format - see <netdb.h> for more details;


  struct hostent
  {
    char    *h_name;               /* official name of host */
    char    **h_aliases;           /* alias list */
    int     h_addrtype;            /* host address type */
    int     h_length;              /* length of address */
    char    **h_addr_list;         /* list of addresses */
    #define h_addr h_addr_list[0]; /* address (compatiblity) */
  };

A Net-BSD standard 'errno' value is returned in R0 if there was an error. See <sys/errno.h> for details of error numbers.

To perform a host address-to-name reverse lookup, call this SWI with the host address converted to a string. eg, "127.0.0.1"

If there is a configuration error (such as Inet$Resolvers not being set), then a RISC OS error block pointer is returned in R0, and the V flag is set on exit.

Resolver_GetHost (SWI 0x46001)

Lookup a hostname string (multi-tasking). On entry

R0	= pointer to host name string, 0 terminated

On exit

R0	= errno integer value if V flag is clear, or
	= error block pointer if V flag is set
R1	= pointer to completed 'hostent' struct if successful,
	= 0 if other state (pending, failed, etc)

All other registers preserved on exit Use This SWI provides a DNS resolution facility that runs in the background (unlike the _GetHostByName) above. Applications need to support additional reason codes however, and some sample code for this is given below.

If the hostname is a valid cache item, or present in the hosts file on disc, it is returned immediately in R1, with R0 set to 0.

If the hostname is a cache item, marked as failed, then R1 is set to NULL (0) and R0 is either -1 (host not found), or -2 (remote failure. eg, configured resolver didn't respond).

If the hostname is a cache item, marked as pending, then R1 is set to NULL (0) and R0 is EINPROGRESS (36 decimal). Items are marked as pending when a remote resolver lookup is in progress.
The calling program is expected to periodically call _GetHost until a valid hostent is returned, or an error condition occurs.

The calling program should run something like;

  EINPROGRESS = 36
  REPEAT
    SYS "Resolver_GetHost","www.ant.co.uk" TO status,hostent;
      flags
    error = flags AND 1
    REM Perhaps inform user of the state of this lookup
  UNTIL (error) OR (status <> EINPROGRESS)
  REM hostent is a valid pointer, or 0

Because name lookups can take anything up to 20 seconds or so, it is important to be able to give feedback to the user on the status of the lookup, as well as giving the foreground application time to perform other tasks.

To perform a host address-to-name reverse lookup, call this SWI with the host address converted to a string. eg, "127.0.0.1"

If there is a configuration error (such as Inet$Resolvers not being set), then a RISC OS error block pointer is returned in R0, and the V flag is set on exit.

Backwards compatibility with _GetHostByAddr

Very old versions of the Resolver module used SWI 0x46001 for a host address to name lookup. For backwards compatibility with older applications, Resolver v0.49 and later still accepts this use of SWI 0x46001.

On entry

R0	= 0
R1	= pointer to host address
R2	= length of address word (ignored)
R3	= address type (ignored)

This performs a single tasking lookup, and otherwise behaves like _GetHostName.

Resolver_GetCache (SWI 0x46002)

Use
For internal use only. This SWI shouldn't be called by application software. Modules that emulate the ANT resolver should return an error.

Resolver_CacheControl (SWI 0x46003)

Use
For internal use only. This SWI shouldn't be called by application software. Modules that emulate the ANT resolver should return an error.

Resolver_XXXXX (SWI 0x460XX)

Use
All other Resolver SWIs are reserved for future development.

Example BASIC programs that use the DNS resolver can be found at DNS examples.

Add a comment to this article

I am sorry to report that no further comments are to be left for articles here. We thank you for past comments. This feature has been disabled.

Email this page to a friend

Last edit: 10th Apr 2016 at 1:55pm
(2937 days ago)

Bookmark with:			What are these?
Delicious	Digg	reddit	Facebook	StumbleUpon

Viewed 7851 times since 12th May 2006,
~ 1 view per day


Home	Blog	Computing	Security	Software	Misc	Wildlife	Links	Feedback		Section Index