resolvlibdoc.c

vxworks source code, used for develop vxworks system.

/* resolvLib/resolvLibDoc.c - DNS resolver library */

/* Copyright 1998-2002 Wind River Systems, Inc */
#include <copyright_wrs.h>

/* 
modification history 
--------------------
01b,25apr02,vvv  updated doc for resolvGetHostByName (SPR #72988)
01a,06oct98,jmp  written from resolvLib.c
*/

/*
DESCRIPTION
This library provides the client-side services for DNS (Domain Name
Service) queries.  DNS queries come from applications that require
translation of IP addresses to host names and back.  If you include 
this library in VxWorks, it extends the services of the host library.  The
interface to this library is described in hostLib.  The hostLib interface 
uses resolver services to get IP and host names. In addition, the resolver
can query multiple DNS servers, if necessary, to add redundancy for queries.  

There are two interfaces available for the resolver library.  One is 
a high-level interface suitable for most applications.  The other is also a
low-level interface for more specialized applications, such as mail protocols.

USING THIS LIBRARY
By default, a VxWorks build does not include the resolver code.  In addition,
VxWorks is delivered with the resolver library disabled.  To include the
resolver library in the VxWorks image, edit config/all/configAll.h and 
include the definition:
.CS
    #define INCLUDE_DNS_RESOLVER
.CE
To enable the resolver services, you need to redefine only one DNS 
server IP address, changing it from a place-holder value to an actual value. 
Additional DNS server IP addresses can be configured using resolvParamsSet().
To do the initial configuration, edit configAll.h, and enter the correct IP 
address for your domain server in the definition:
.CS
    #define RESOLVER_DOMAIN_SERVER  "90.0.0.3"
.CE
If you do not provide a valid IP address, resolver initialization fails.  
You also need to configure the domain to which your resolver belongs.  To 
do this, edit configAll.h and enter the correct domain name for your 
organization in the definition:
.CS
    #define RESOLVER_DOMAIN  "wrs.com"
.CE
The last and most important step is to make sure that you have a route to 
the configured DNS server.  If your VxWorks image includes a routing protocol, 
such as RIP or OSPF, the routes are created for you automatically.  Otherwise,
you must use routeAdd() or mRouteAdd() to add the routes to the routing table.

The resolver library comes with a debug option.  To turn on debugging, 
edit configAll.h to include the define:
.CS
    #define INCLUDE_DNS_DEBUG
.CE
This include makes VxWorks print a log of the resolver queries to the console.
This feature assumes a single task.  Thus, if you are running multiple tasks,
your output to the console is a garble of messages from all the tasks.

The resolver library uses UDP to send queries to the DNS server and expects
the DNS server to handle recursion.  You can change the resolver parameters 
at any time after the library has been initialized with resolvInit().
However, it is strongly recommended that you change parameters only shortly 
after initialization, or when there are no other tasks accessing the resolver
library.  

Your procedure for changing any of the resolver parameter should start
with a call to resolvParamsGet() to retrieve the active parameters.  Then
you can change the query order (defaults to query DNS server only), the 
domain name, or add DNS server IP addresses.  After the parameters are
changed, call resolvParamsSet().  For the values you can use when accessing 
resolver library services, see the header files resolvLib.h, resolv/resolv.h, 
and resolv/nameser.h. 

INCLUDE FILES: resolvLib.h 
SEE ALSO
hostLib
*/

/*******************************************************************************
*
* resolvInit - initialize the resolver library 
*
* This function initializes the resolver.  <pNameServer> is a single IP address
* for a name server in dotted decimal notation.  <pDefaultDomainName> is the 
* default domain name to be appended to names without a dot.  The function 
* pointer <pdnsDebugRtn> is set to the resolver debug function.  Additional
* name servers can be configured using the function resolvParamsSet().
*
* RETURNS: OK or ERROR.
*
* SEE ALSO:
* resolvGetHostByName(), resolvGetHostByAddr(), resolvDNExpand(),
* resolvDNComp(), resolvSend(), resolvParamsSet(), resolvParamsGet(),
* resolvQuery()
*/

STATUS resolvInit
    (
    char *     pNameServer,	    /* pointer to Name server IP address */
    char *     pDefaultDomainName,  /* default domain name */
    FUNCPTR    pdnsDebugRtn         /* function ptr to debug routine */
    )
    {
    ...
    }

/*******************************************************************************
*
* resolvGetHostByName - query the DNS server for the IP address of a host
*
* This function returns a `hostent' structure. This structure is defined as
* follows: 
*
* .CS
*     struct   hostent 
*     {
*     char *   h_name;          /@ official name of host @/ 
*     char **  h_aliases;       /@ alias list @/
*     int      h_addrtype;      /@ address type @/
*     int      h_length;        /@ length of address @/ 
*     char **  h_addr_list;     /@ list of addresses from name server @/
*     unsigned int h_ttl;       /@ Time to Live in Seconds for this entry @/
*     }
* .CE
* The `h_aliases' and `h_addr_list' vectors are NULL-terminated. For a locally
* resolved entry `h_ttl' is always 60 (an externally resolved entry may also
* have a TTL of 60 depending on its age but it is usually much higher).
*
* Specify the host you want to query in <pHostname>.  Use <pBuf> and <bufLen> 
* to specify the location and size of a buffer to receive the `hostent' 
* structure and its associated contents.  Host addresses are returned in 
* network byte order.  Given the information this routine retrieves, the 
* <pBuf> buffer should be 512 bytes or larger.
*
* RETURNS: A pointer to a `hostent' structure if the host is found, or 
* NULL if the parameters are invalid, the host is not found, or the 
* buffer is too small.
*
* ERRNO:
*  S_resolvLib_INVALID_PARAMETER
*  S_resolvLib_BUFFER_2_SMALL
*  S_resolvLib_TRY_AGAIN
*  S_resolvLib_HOST_NOT_FOUND
*  S_resolvLib_NO_DATA
*  S_resolvLib_NO_RECOVERY
* 
* SEE ALSO:
* resolvInit(), resolvGetHostByAddr(), resolvDNExpand(),
* resolvDNComp(), resolvSend(), resolvParamsSet(), resolvParamsGet(),
* resolvMkQuery(), resolvQuery()
*/
struct hostent *  resolvGetHostByName
    (
    char *     pHostName,  /* ptr to the name of  the host */
    char *     pHostBuf,   /* ptr to the buffer used by hostent structure */
    int        bufLen      /* length of the buffer */ 
    )
    {
    ...
    }

/*******************************************************************************
*
* resolvGetHostByAddr - query the DNS server for the host name of an IP address
*
* This function returns a `hostent' structure, which is defined as follows:
*
* .CS
* struct   hostent 
*     {
*     char *   h_name;            /@ official name of host @/
*     char **  h_aliases;         /@ alias list @/
*     int      h_addrtype;        /@ address type @/
*     int      h_length;          /@ length of address @/
*     char **  h_addr_list;       /@ list of addresses from name server @/
*     unsigned int h_ttl;         /@ Time to Live in Seconds for this entry @/
*     }
* .CE
* The `h_aliases' and `h_addr_list' vectors are NULL-terminated. For a locally
* resolved entry `h_ttl' is always 60 (an externally resolved entry may also
* have a TTL of 60 depending on its age but it is usually much higher).
*
* The <pinetAddr> parameter passes in the IP address (in network byte order)
* for the host whose name you want to discover.  The <pBuf> and <bufLen> 
* parameters specify the location and size (512 bytes or more) of the buffer 
* that is to receive the hostent structure.  resolvGetHostByAddr() returns 
* host addresses are returned in network byte order. 
*
* RETURNS: A pointer to a `hostent' structure if the host is found, or 
* NULL if the parameters are invalid, host is not found, or the buffer 
* is too small.
* 
* ERRNO:
*  S_resolvLib_INVALID_PARAMETER
*  S_resolvLib_BUFFER_2_SMALL
*  S_resolvLib_TRY_AGAIN
*  S_resolvLib_HOST_NOT_FOUND
*  S_resolvLib_NO_DATA
*  S_resolvLib_NO_RECOVERY
*
* SEE ALSO:
* resolvGetHostByName(), resolvInit(), resolvDNExpand(),
* resolvDNComp(), resolvSend(), resolvParamsSet(), resolvParamsGet(),
* resolvMkQuery(), resolvQuery()
*/

struct hostent *     resolvGetHostByAddr 
    (
    const char *       pInetAddr,
    char *             pHostBuf,
    int                bufLen
    )
    {
    ...
    }

/*******************************************************************************
*
* resolvParamsSet - set the parameters which control the resolver library
*
* This routine sets the resolver parameters.  <pResolvParams> passes in
* a pointer to a RESOLV_PARAMS_S structure, which is defined as follows: 
* .CS
*     typedef struct
*        {
*        char   queryOrder;
*        char   domainName [MAXDNAME];
*        char   nameServersAddr [MAXNS][MAXIPADDRLEN];
*        } RESOLV_PARAMS_S;
* .CE
* Use the members of this structure to specify the settings you want to 
* apply to the resolver.  It is important to remember that multiple tasks 
* can use the resolver library and that the settings specified in 
* this RESOLV_PARAMS_S structure affect all queries from all tasks.  In 
* addition, you should set resolver parameters at initialization and not 
* while queries could be in progress. Otherwise, the results of the query 
* are unpredictable.  
*
* Before calling resolvParamsSet(), you should first call resolvParamsGet() 
* to populate a RESOLV_PARAMS_S structure with the current settings.  Then
* you change the values of the members that interest you.    
*
* Valid values for the `queryOrder' member of RESOLV_PARAMS_S structure 
* are defined in resolvLib.h.  Set the `domainName' member to the domain to 
* which this resolver belongs.  Set the `nameServersAddr' member to the IP 
* addresses of the DNS server that the resolver can query.  You must specify 
* the IP addresses in standard dotted decimal notation.  This function tries 
* to validate the values in the `queryOrder' and `nameServerAddr' members.  
* This function does not try to validate the domain name.  
*
* RETURNS: OK if the parameters are valid, ERROR otherwise.
*
* SEE ALSO:
* resolvGetHostByName(), resolvGetHostByAddr(), resolvDNExpand(),
* resolvDNComp(), resolvSend(), resolvInit(), resolvParamsGet(),
* resolvMkQuery(), resolvQuery()
*/

STATUS resolvParamsSet 
    (
    RESOLV_PARAMS_S *  pResolvParams  /* ptr to resolver parameter struct */
    )
    {
    ...
    }