Internet based applications are required to connect to other hosts throughout the world. Location of these hosts is via numeric addresses which are determined by human readable names. The process of converting from names to addresses is performed by 'Domain Name Servers' (DNS).
Under RISC OS, communication with DNS is performed by the Resolver module.
This chapter describes how the Resolver module is configured to use DNS, and applications should interact with it.
The Resolver module provides shared Internet IP address resolution facilities to the system.
The Hosts file is the file InetDBase:Hosts. It is used to initialise the local DNS cache with entries.
DNS servers are queried by the Resolver and the results are cached.
Application is used within this chapter as a description of the Resolver querant, but this may also apply to Modules.
The Resolver functions as follows :
The module provides two interfaces for resolving addresses :
In addition, there is a means for controlling the cache :
All results are returned in the form of NetBSD standard 'hostent' structures. These structures should be considered to be read only by the application.
A hostent has the following structure :
| Offset | Contents |
|---|---|
| +0 | Pointer to host name |
| +4 | Pointer to 0 terminated list of pointers to aliases for this host |
| +8 | Address type (usually AF_INET) |
| +12 | Address length (4 for AF_INET) |
| +16 | Pointer to 0 terminated list of addresses |
The Resolver module uses a number of system variables for its configuration. These determine how and where it resolves Internet addresses from. In general, these variables are initialised during machine startup. They may be modified by the user once the Internet stack has started. They will be read when the re-configure call is made to the Resolver, either via the Resolver_CacheControl SWI or by the *ResolverConfig command. In addition, they will be re-read whenever the InetDBaseChanged service is issued.
This variable lists the DNS servers that will be queried during resolution requestes. It consists of a space separated list of dotted IP addresses. Up to three addresses may be supplied. Addresses will be queried in the order supplied.
This variable gives the local name of this host. Attempts to set this
variable to a fully qualified hostname will result in it and
Inet$LocalDomain being set to the correct values.
This variable gives the local domain name for the network this host is
connected to. Together with Inet$Hostname, this provides
the name of this host on a network. It may be that this host name is
not visible from certain networks due to firewalls, proxying and other
network-specific issues.
This variable describes the domains which should be appended to failed host lookups in an attempt to resolve them.
After being modified, the Resolver module must be notified by requesting it re-read its configuration.
This variable should be set to the number of retries that the resolve should made. During resolution, the Resolver may get no response to its requests. This may be due to network bandwidth limitations, or a busy server. The number of retries may be configured to allow for greater numbers of retries if necessary.
After being modified, the Resolver module must be notified by requesting it re-read its configuration.
This variable should be set to the number of seconds that should be waited between resolution requests. During resolution, the Resolver may get no response to its requests. This may be due to network bandwidth limitations, or a busy server. The delay between retries may be configured to allow for faster requests (if the server is known to accept such requests - consult the server operators) or longer delays if the server is known to be under load.
After being modified, the Resolver module must be notified by requesting it re-read its configuration.
This variable should be set to '1' to configure the DNS relay to be active, or '0' to deactivate it.
After being modified, the Resolver module must be notified by requesting it re-read its configuration.
| R0 | = | reason code :
| ||||||||
| R1 | = | service call number |
| R0 | preserved | |
| R1 | preserved | |
This service is issued by the Resolver module when certain variables that it monitors change. Other components may use the service as an indication that their configuration has changed.
| R0 | = | 0 (reason code) |
| R1 | = | service call number |
| R0 | preserved | |
| R1 | preserved | |
This service is issued by the Resolver module when
InetDBase$Path is changed. Components which hold resources
in the database should re-read those resources.
| R0 | = | 1 (reason code) |
| R1 | = | service call number |
| R0 | preserved | |
| R1 | preserved | |
This service is issued by the Resolver module when Inet$Hostname is changed. Components which use the hostname to refer to objects should update their concept of the local name
| R1 | = | Pointer to host name string |
| R0 | = | Internet error number, indicating the state of the lookup :
| ||||||||||||
| R1 | = | Pointer to 'hostent' structure if successful, or 0 if failed |
This SWI is provided primarily for backwards compatibility, since new network applications can use the more flexible Resolver_GetHost.
The main use of this SWI is by the simple ports of unix applications using the gethostbyname() function call.
Although this SWI is marked as non-reentrant, it is expected that this SWI be preempted by OS_UpCall 6 when used in a TaskWindow. This is a safe operation.
| R1 | = | Pointer to host name string |
| R0 | = | Internet error number, indicating the state of the lookup :
| ||||||||||||
| R1 | = | Pointer to 'hostent' structure if successful, or 0 if failed |
This SWI provides a DNS resolution facility that runs in the background (unlike Resolver_GetHostByName). Applications must poll the Resolver module for the state of the resolution.
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 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 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 Resolver_GetHost until a valid hostent is returned, or an error condition occurs.
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.
Cache sweeps occur periodically - pending items are marked as failed (remote failure) after a short period, failed items are removed after a longer period, and valid items are removed after 24 hours.
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.
The calling program might run something like:
REM 'EINPROGRESS' error number is 36 decimal REPEAT SYS "Resolver_GetHost","host.net" TO status,hostent;flags error = (flags AND 1) == 1 REM Perhaps inform user of the state of this lookup UNTIL (error) OR (status != EINPROGRESS) REM hostent is a valid pointer, or 0
This SWI call is for internal use only. You must not use it in your own code.
| R0 | = | Reason code :
|
| R0 | preserved | |
This SWI is provided to allow a calling application to control the Resolver cache in a limited way. Currently, the only reason codes supported are to force flushes of certain cache entries, and dis(abling) of the caching of lookups that fail.
Caching of lookup failures is disabled by default. You might wish to enable the caching of lookup failures if you are sure that any failures are genuine bad host errors and not due to packet loss, remote server timeouts, etc.
*ResolverConfig
This command is used to request that the Resolver re-read the system variables for configuration.
*ResolverConfig
| Maintainer(s): | RISCOS Ltd <developer@riscos.com> | ||||||||
|---|---|---|---|---|---|---|---|---|---|
| History: |
| ||||||||
| Disclaimer: |
Copyright © Pace Micro Technolgy plc, 2002. |