home *** CD-ROM | disk | FTP | other *** search
/ ARM Club 3 / TheARMClub_PDCD3.iso / hensa / internet / dnsquery_1 / h / dnsquery next >
Text File  |  1996-02-08  |  10KB  |  236 lines
  1. /*
  2.  *  DNSQuery.h
  3.  *
  4.  *  A multiply threadable, multitasking DNS resolver
  5.  *
  6.  *  Copyright (C) Stewart Brodie, February 1996.
  7.  *  Portions are copyright Regents of the University California Berkeley
  8.  *
  9.  *  This code may be freely used in applications designed to work with the
  10.  *  Acorn TCP/IP stack or FreeNet or compatible stacks for RISC OS, provided
  11.  *  that a copy of the UCB copyright & disclaimer message is included, and
  12.  *  also my own disclaimer.
  13.  *
  14.  *  This code is based on the res_ function code from BIND-4.9.3-REL
  15.  *  but with extensive modifications to make it state driven.
  16.  * 
  17.  *  enum dns_status should be treated as an opaque status code except
  18.  *  for dns_query_complete_success and dns_query_complete_failure
  19.  *
  20.  *  Function veneers described with the functions.  The only supported
  21.  *  address class is C_IN.  Lots of the explanations contain VITAL
  22.  *  information about how to use the API provided, and an explanation
  23.  *  of the internal workings is provided where necessary.
  24.  *
  25.  */
  26.  
  27. #ifndef dnsquery_h_included
  28. #define dnsquery_h_included
  29. #ifdef __cplusplus
  30. extern "C" {
  31. #endif
  32.  
  33. /* An abstract handle on the query */
  34. typedef struct dnsquery dnsquery;
  35.  
  36. /* See comment above about dns_status */
  37. typedef enum {
  38.         dns_query_init,
  39.         dns_query_next_ns,
  40.     dns_query_same_ns,
  41.         dns_query_complete_success,
  42.         dns_query_complete_failure,
  43.  
  44.     dns_query_v_circuit_init,
  45.     dns_query_v_circuit_connect,
  46.     dns_query_v_circuit_recv,
  47.     dns_query_v_circuit_polling_connect,
  48.     dns_query_v_circuit_connect_succeeded,
  49.     dns_query_v_circuit_select_for_reading,
  50.     dns_query_v_circuit_reading_size,
  51.     dns_query_v_circuit_init_main_answer,
  52.     dns_query_v_circuit_read_main_answer,
  53.     dns_query_v_circuit_junk,
  54.  
  55.     dns_query_dgram_wait_timeout,
  56.     dns_query_dgram_blocked_select,
  57.     dns_query_dgram_select_result,
  58.  
  59.     dns_query_converged_after_if,
  60.     
  61.     dns_query_running_subquery
  62. } dns_status;
  63.  
  64. /* dnsquery *dnsquery_new(char *data, int C_??, int T_?? )
  65.  *
  66.  * Start a new query with class C_?? and type T_?? with the
  67.  * data given, which is dependent on T_??.  C_ and T_ values
  68.  * may be found in netlib:arpa.h.nameser.  Do not use this
  69.  * API for C_IN/T_A or C_IN/T_PTR unless you wish to bypass
  70.  * the search semantics and faking of dotted-quads into hosts
  71.  * normally done by gethostbyname, and the automatic data
  72.  * creation of gethostbyaddr.  The parameter meanings are the
  73.  * same as for res_query.
  74.  *
  75.  * Returns: handle to the query, or NULL if failed to create it
  76.  */
  77. extern dnsquery *dnsquery_new(char *, int , int);
  78.  
  79. /* dnsquery *dnsquery_gethostbyaddr(char *addr, int size, int addrclass)
  80.  *
  81.  * Start a multitasking version of gethostbyaddr. Parameters are the
  82.  * same as for the standard call.  addrclass should be C_IN.  size
  83.  * must be 4 (ie. can't handle IPv6 lookups yet).  Although a char *,
  84.  * the addr parameter is a pointer to the 4 byte IP address in network
  85.  * order.
  86.  *
  87.  * Returns: handle to the query, or NULL if failed to create it
  88.  */
  89. extern dnsquery *dnsquery_gethostbyaddr(char *, int ,int);
  90.  
  91. /* dnsquery *dnsquery_gethostbyname(char *name)
  92.  *
  93.  * Starts a multitasking version of gethostbyname.  Parameter is the
  94.  * hostname to lookup.  Dotted-quad lookups are trapped (ie. if you
  95.  * ask for dnsquery_gethostbyname("152.78.67.42") then you will get an
  96.  * artificially created answer bypassing the DNS.  This function will
  97.  * implement the usual semantics of res_search by searching all the
  98.  * domains specified in the resconf file.  The multiple lookups which
  99.  * may be generated are handled transparently.
  100.  *
  101.  * Returns: handle to the query, or NULL if failed to create it
  102.  */
  103. extern dnsquery *dnsquery_gethostbyname(char *);
  104.  
  105. /* dns_status dnsquery_check(dnsquery *query)
  106.  *
  107.  * Checks on the progress of 'query'.  The return value comes from
  108.  * the enum given earlier in this file.  The only determination
  109.  * the client can make from this result is whether the query is
  110.  * still in progress, or has finished.  dns_query_complete_failure
  111.  * represents a failure of some kind (you can't tell what), whereas
  112.  * dns_query_complete_success represents a success of some kind.
  113.  *
  114.  * The purpose of this call is not just to check whether it has
  115.  * completed, but to step through the internal state table in order
  116.  * to make the resolver work.  The code will loop internally whilst
  117.  * it isn't waiting for a response from the network, the implication
  118.  * of this being that if this function returns and the status is NOT
  119.  * one of the two finished states (see above) then it is waiting for
  120.  * a timeout or data to arrive.
  121.  *
  122.  * You can call this function as frequently or infrequently as you
  123.  * wish.  You may, for example, call SWI Wimp_Poll between calls to
  124.  * this function.  However, in order to implement the correct timeout
  125.  * of failing calls, you must call this function regularly.  This
  126.  * library does not do anything in the background, and will only
  127.  * notice timeouts if you call this function.
  128.  *
  129.  * >> IMPORTANT NOTE: the definition of 'success' is that none of
  130.  * >> the SWI calls to the TCP/IP stack failed.  Hence the query
  131.  * >> may not have been answered - you need to retrieve the answer
  132.  * >> in order to find out whether any answer was obtained.
  133.  */
  134. extern dns_status dnsquery_check(dnsquery *);
  135.  
  136. /* void dnsquery_dispose(dnsquery *query)
  137.  *
  138.  * Destroys the internal data structures associated with 'query'.
  139.  * 'query' must be a value which was returned by an earlier call
  140.  * to one of the dnsquery_ functions, and must not have been
  141.  * passed to this function before, unless it was subsequently
  142.  * returned by another dnsquery_ function after such a call.
  143.  * (Basically, don't free the same thing twice! :-)  The current
  144.  * SharedCLibrary will cause your application to exit silently
  145.  * if you do.
  146.  */
  147. extern void dnsquery_dispose(dnsquery *);
  148.  
  149.  
  150. /* struct hostent *dnsquery_getanswer(dnsquery *query)
  151.  *
  152.  * Returns a pointer to a *static* buffer within the dnsquery
  153.  * data area representing the result of a 'query' which was started
  154.  * with either dnsquery_gethostbyaddr or dnsquery_gethostbyaddr.
  155.  * You must NOT make this call if the query was started with
  156.  * dnsquery_new() EVEN IF it was a T_A or T_PTR lookup.  However,
  157.  * any query which can be validly passed to this function may also
  158.  * be passed to dnsquery_getanswerraw described below.
  159.  *
  160.  * You must only ever make this call after dnsquery_check(query) has
  161.  * returned dns_query_complete_success.  You must not make this call
  162.  * after 'query' has been passed to dnsquery_dispose.
  163.  *
  164.  * You can make this call more than once in between those two states
  165.  * although you should realise that you will suffer a performance hit
  166.  * from doing this (the library has to make a lot of calls to malloc
  167.  * and free whilst creating the struct hostent).
  168.  *
  169.  * >> IMPORTANT NOTE: You are returned a pointer to a struct hostent.
  170.  * >> This buffer WILL be corrupted by later calls to this function,
  171.  * >> AND ALSO by calls to the standard gethostbyname and gethostbyaddr
  172.  * >> functions usually associated with DNS resolver libraries.
  173.  */
  174. extern struct hostent *dnsquery_getanswer(dnsquery *);
  175.  
  176. /* void *dnsquery_getanswerraw(dnsquery *query, int *answersize)
  177.  *
  178.  * Similar to dnsquery_getanswer, but used when that function cannot
  179.  * be called (for reasons given above).
  180.  *
  181.  * You must only ever make this call after dnsquery_check(query) has
  182.  * returned dns_query_complete_success.  You must not make this call
  183.  * after 'query' has been passed to dnsquery_dispose.
  184.  *
  185.  * You can make this call more than once in between those two states,
  186.  * although there is no performance hit with this function call
  187.  *
  188.  * This function returns you a pointer to the query result as returned
  189.  * by the remote DNS server which responded to the query, and will store
  190.  * the size of the result in the given answersize variable.  This is a
  191.  * result-only parameter.  The returned pointer remains valid until
  192.  * the 'query' has been passed to dnsquery_dispose.  You must parse
  193.  * the response yourself (or port the resparse application (not yet
  194.  * supplied) to find the answer IF THERE IS ONE).  The ancount of the
  195.  * query may be zero (indicating no answers have been returned).
  196.  *
  197.  */
  198. extern void *dnsquery_getanswerraw(dnsquery *, int *);
  199.  
  200. /*
  201.  * int dnsquery_check_nameservers(struct sockaddr_in **ptr_to_servers)
  202.  *
  203.  * This function can be used to find out which nameservers are
  204.  * being used by the dnsquery library.  Internally, the library
  205.  * maintains an array of 'struct sockaddr_in' structures, and
  206.  * the address of the first element of this array is stored in
  207.  * the ptr_to_servers parameter which you supply.  The int result
  208.  * is a count of the number of nameservers in the array.  The
  209.  * maximum value that this will be is MAXNS, defined in netlib:h.resolv
  210.  * although this information is of no real concern to the client.
  211.  *
  212.  * If this function returns zero, then the pointer is indeterminate,
  213.  * and it may have been modified.  A zero return means that there are
  214.  * no nameservers, a situation which is either deliberate (because
  215.  * you aren't on the Internet or don't have a DNS server), or you
  216.  * are relying on the InetDbase:hosts file to satisfy all requests.
  217.  *
  218.  * >> NOTE: This is a struct sockaddr_in and NOT struct in_addr.
  219.  * >> The structures are used internally in calls to sendto() and
  220.  * >> connect() and must therefore be treated as read-only (unless
  221.  * >> you deliberately wish to alter the nameservers being used, of
  222.  * >> course!)
  223.  *
  224.  * If you want to change the number of nameservers, then you must
  225.  * manipulate _res.nscount directly, and ensure that _res.nscount
  226.  * does not exceed MAXNS, and ensure that enough of the struct
  227.  * sockaddr_in structures have been setup correctly too. See
  228.  * resolv.h for details.
  229.  */
  230. extern int dnsquery_check_nameservers(struct sockaddr_in **);
  231.  
  232. #ifdef __cplusplus
  233. }
  234. #endif
  235. #endif
  236.