src/adns.h

   1 /**/
   2
   3 #ifndef ADNS_H_INCLUDED
   4 #define ADNS_H_INCLUDED
   5
   6 typedef struct adns__state adns_state;
   7 typedef struct adns__query adns_query;
   8
   9 typedef enum {
  10   adns_if_noenv=      0x0001, /* do not look at environment */
  11   adns_if_noerrprint= 0x0002, /* never print output to stderr */
  12   adns_if_debug=      0x0004, /* print debugging output to stderr */
  13 } adns_initflags;
  14
  15 typedef enum {
  16   adns_f_search=     0x0001, /* use the searchlist */
  17   adns_f_usevc=      0x0002, /* use a virtual circuit (TCP connection) */
  18 } adns_queryflags;
  19
  20 typedef enum {
  21   adns_rrttype_mask=  0x0fff,
  22   adns_qtf_deref=     0x1000,
  23   adns_qtf_mailconv=  0x2000,
  24   adns_r_none=             0,
  25   adns_r_a=                1,
  26   adns_r_ns_raw=           2,
  27   adns_r_ns=                  adns_r_ns_raw|adns_qtf_deref,
  28   adns_r_cname=            5,
  29   adns_r_soa_raw=          6,
  30   adns_r_soa=                 adns_r_soa_raw|adns_qtf_mailconv,
  31   adns_r_null=            10,
  32   adns_r_ptr_raw=         12,
  33   adns_r_ptr=                 adns_r_ptr_raw|adns_rf_deref,
  34   adns_r_hinfo=           13,
  35   adns_r_mx_raw=          15,
  36   adns_r_mx=                  adns_r_mx_raw|adns_qtf_deref,
  37   adns_r_txt=             16,
  38   adns_r_rp_raw           17,
  39   adns_r_rp=                  adns_r_rp_raw|adns_qtf_mailconv
  40 } adns_rrtype;
  41
  42 typedef enum {
  43   adns_s_ok,
  44   adns_s_notresponding,
  45   adns_s_serverfailure,
  46   adns_s_unknownqtype,
  47   adns_s_remoteerror,
  48   adns_s_max_tempfail= 99,
  49   adns_s_nxdomain,
  50   adns_s_norecord,
  51   adns_s_invaliddomain
  52 } adns_status;
  53
  54 /* In dereferenced answers, multiple addresses show up as multiple
  55  * answers with all the dm pointers being the same.  If no
  56  * address is available (permanent failure) then INADDR_NONE is
  57  * used. */
  58
  59 struct adns_answer {
  60   adns_status status;
  61   char *cname; /* always NULL if query was for CNAME records */
  62   adns_rrtype type;
  63   int nrrs;
  64   union {
  65     struct in_addr inaddr[1];                                          /* a */
  66     char (*str)[1];                     /* ns_raw, cname, ptr, ptr_raw, txt */
  67     struct { char *dm; struct in_addr addr; } dmaddr;                 /* ns */
  68     struct { char *a, *b; } strpair[1];                /* hinfo, rp, rp_raw */
  69     struct { int pref; char *dm; struct in_addr addr; } intdmaddr[1]; /* mx */
  70     struct { int pref; char *str; } intstr[1]; /* mx_raw */
  71     struct {
  72       char *ns0, *rp;
  73       unsigned long serial, refresh, retry, expire, minimum;
  74     } soa[1]; /* soa, soa_raw */
  75     /* NULL is empty */
  76   } rrs;
  77 };
  78
  79 /* Memory management:
  80  *  adns_state and adns_query are actually pointers to malloc'd state;
  81  *  On submission questions are copied, including the owner domain;
  82  *  Answers are malloc'd as a single piece of memory.
  83  * query_io:
  84  *  Must always be non-null pointer;
  85  *  If *query_io is 0 to start with then any query may be returned;
  86  *  If *query_io is !0 adns_query then only that query may be returned.
  87  * Errors:
  88  *  Return values are 0 or an errno value;
  89  *  Seriously fatal system errors (eg, failure to create sockets,
  90  *  malloc failure, etc.) return errno values;
  91  *  Other errors (nameserver failure, timed out connections, &c)
  92  *  are returned in the status field of the answer.  If status is
  93  *  nonzero then nrrs will be 0, otherwise it will be >0.
  94  *  type will always be the type requested;
  95  *  If no (appropriate) requests are done adns_query returns EWOULDBLOCK;
  96  *  If no requests are outstanding adns_query and adns_wait return ESRCH;
  97  *  If malloc failure occurs during internal allocation or processing
  98  *  ands_query, _wait and _answer set *answer to 0.
  99  */
 100
 101 int adns_init(adns_state *newstate_r);
 102
 103 int adns_synchronous(adns_state ads,
 104                      const char *owner,
 105                      adns_rrtype type,
 106                      int flags,
 107                      struct adns_answer *answer);
 108
 109 int adns_submit(adns_state ads,
 110                 const char *owner,
 111                 adns_rrtype type,
 112                 int flags,
 113                 void *context,
 114                 const struct adns_query *query_r);
 115
 116 int adns_query(adns_state ads,
 117                adns_query *query_io,
 118                struct adns_answer *answer,
 119                void *context_r);
 120
 121 int adns_wait(adns_state ads,
 122               adns_query *query_io,
 123               struct adns_answer *answer,
 124                void *context_r);
 125
 126 int adns_cancel(adns_state ads, adns_query query);
 127
 128 int adns_finish(adns_state);
 129
 130 void adns_event(adns_state, fd_set *readfds_mod,
 131                 fd_set *writefds_mod, fd_set *exceptfds_mod,
 132                 int *maxfd_mod, struct timeval *tv_mod);
 133 /* You may call this with *_mod=0 to have a simple callback,
 134    or with *fds_mod=*maxfd_mod=0 but tv_mod!=0 if you are
 135    not going to sleep, or with all !=0 if you are going to sleep. */
 136
 137 /* Example expected/legal calling sequences:
 138  *  adns_init
 139  *  adns_submit 1
 140  *  adns_submit 2
 141  *  adns_submit 3
 142  *  adns_wait 1
 143  *  adns_query 3 -> EWOULDBLOCK
 144  *  adns_wait 2
 145  *  adns_wait 3
 146  *  ....
 147  *  adns_finish
 148  *
 149  *  adns_init
 150  *  adns_submit ...
 151  *  loop {
 152  *   adns_query
 153  *   adns_interest
 154  *   select
 155  *   adns_callback
 156  *   other things
 157  *  }
 158  */
 159
 160 #endif