contrib/ldns/ldns/resolver.h

   1 /*
   2  * resolver.h
   3  *
   4  * DNS Resolver definitions
   5  *
   6  * a Net::DNS like library for C
   7  *
   8  * (c) NLnet Labs, 2005-2006
   9  *
  10  * See the file LICENSE for the license
  11  */
  12
  13 /**
  14  * \file
  15  *
  16  * Defines the  ldns_resolver structure, a stub resolver that can send queries and parse answers.
  17  *
  18  */
  19
  20 #ifndef LDNS_RESOLVER_H
  21 #define LDNS_RESOLVER_H
  22
  23 #include <ldns/error.h>
  24 #include <ldns/common.h>
  25 #include <ldns/rr.h>
  26 #include <ldns/tsig.h>
  27 #include <ldns/rdata.h>
  28 #include <ldns/packet.h>
  29 #include <sys/time.h>
  30
  31 #ifdef __cplusplus
  32 extern "C" {
  33 #endif
  34
  35 /** Default location of the resolv.conf file */
  36 #define LDNS_RESOLV_CONF        "/etc/resolv.conf"
  37 /** Default location of the hosts file */
  38 #define LDNS_RESOLV_HOSTS       "/etc/hosts"
  39
  40 #define LDNS_RESOLV_KEYWORD     -1
  41 #define LDNS_RESOLV_DEFDOMAIN   0
  42 #define LDNS_RESOLV_NAMESERVER  1
  43 #define LDNS_RESOLV_SEARCH      2
  44 #define LDNS_RESOLV_SORTLIST    3
  45 #define LDNS_RESOLV_OPTIONS     4
  46 #define LDNS_RESOLV_ANCHOR      5
  47 #define LDNS_RESOLV_KEYWORDS    6
  48
  49 #define LDNS_RESOLV_INETANY             0
  50 #define LDNS_RESOLV_INET                1
  51 #define LDNS_RESOLV_INET6               2
  52
  53 #define LDNS_RESOLV_RTT_INF             0       /* infinity */
  54 #define LDNS_RESOLV_RTT_MIN             1       /* reachable */
  55
  56 /**
  57  * DNS stub resolver structure
  58  */
  59 struct ldns_struct_resolver
  60 {
  61         /**  Port to send queries to */
  62         uint16_t _port;
  63
  64         /** Array of nameservers to query (IP addresses or dnames) */
  65         ldns_rdf **_nameservers;
  66         /** Number of nameservers in \c _nameservers */
  67         size_t _nameserver_count; /* how many do we have */
  68
  69         /**  Round trip time; 0 -> infinity. Unit: ms? */
  70         size_t *_rtt;
  71
  72         /**  Whether or not to be recursive */
  73         bool _recursive;
  74
  75         /**  Print debug information */
  76         bool _debug;
  77
  78         /**  Default domain to add to non fully qualified domain names */
  79         ldns_rdf *_domain;
  80
  81         /**  Searchlist array, add the names in this array if a query cannot be found */
  82         ldns_rdf **_searchlist;
  83
  84         /** Number of entries in the searchlist array */
  85         size_t _searchlist_count;
  86
  87         /**  Number of times to retry before giving up */
  88         uint8_t _retry;
  89         /**  Time to wait before retrying */
  90         uint8_t _retrans;
  91         /**  Use new fallback mechanism (try EDNS, then do TCP) */
  92         bool _fallback;
  93
  94         /**  Whether to do DNSSEC */
  95         bool _dnssec;
  96         /**  Whether to set the CD bit on DNSSEC requests */
  97         bool _dnssec_cd;
  98         /** Optional trust anchors for complete DNSSEC validation */
  99         ldns_rr_list * _dnssec_anchors;
 100         /**  Whether to use tcp or udp (tcp if the value is true)*/
 101         bool _usevc;
 102         /**  Whether to ignore the tc bit */
 103         bool _igntc;
 104         /**  Whether to use ip6: 0->does not matter, 1 is IPv4, 2 is IPv6 */
 105         uint8_t _ip6;
 106         /**  If true append the default domain */
 107         bool _defnames;
 108         /**  If true apply the search list */
 109         bool _dnsrch;
 110         /**  Timeout for socket connections */
 111         struct timeval _timeout;
 112         /**  Only try the first nameserver, and return with an error directly if it fails */
 113         bool _fail;
 114         /**  Randomly choose a nameserver */
 115         bool _random;
 116         /** Keep some things to make AXFR possible */
 117         int _socket;
 118         /** Count the number of LDNS_RR_TYPE_SOA RRs we have seen so far
 119          * (the second one signifies the end of the AXFR)
 120          */
 121         int _axfr_soa_count;
 122         /* when axfring we get complete packets from the server
 123            but we want to give the caller 1 rr at a time, so
 124            keep the current pkt */
 125         /** Packet currently handled when doing part of an AXFR */
 126         ldns_pkt *_cur_axfr_pkt;
 127         /** Counter for within the AXFR packets */
 128         uint16_t _axfr_i;
 129         /* EDNS0 available buffer size */
 130         uint16_t _edns_udp_size;
 131         /* serial for IXFR */
 132         uint32_t _serial;
 133
 134         /* Optional tsig key for signing queries,
 135         outgoing messages are signed if and only if both are set
 136         */
 137         /** Name of the key to use with TSIG, if _tsig_keyname and _tsig_keydata both contain values, outgoing messages are automatically signed with TSIG. */
 138         char *_tsig_keyname;
 139         /** Secret key data to use with TSIG, if _tsig_keyname and _tsig_keydata both contain values, outgoing messages are automatically signed with TSIG. */
 140         char *_tsig_keydata;
 141         /** TSIG signing algorithm */
 142         char *_tsig_algorithm;
 143
 144         /** Source address to query from */
 145         ldns_rdf *_source;
 146 };
 147 typedef struct ldns_struct_resolver ldns_resolver;
 148
 149 /* prototypes */
 150 /* read access functions */
 151
 152 /**
 153  * Get the port the resolver should use
 154  * \param[in] r the resolver
 155  * \return the port number
 156  */
 157 uint16_t ldns_resolver_port(const ldns_resolver *r);
 158
 159 /**
 160  * Get the source address the resolver should use
 161  * \param[in] r the resolver
 162  * \return the source rdf
 163  */
 164 ldns_rdf *ldns_resolver_source(const ldns_resolver *r);
 165
 166 /**
 167  * Is the resolver set to recurse
 168  * \param[in] r the resolver
 169  * \return true if so, otherwise false
 170  */
 171 bool ldns_resolver_recursive(const ldns_resolver *r);
 172
 173 /**
 174  * Get the debug status of the resolver
 175  * \param[in] r the resolver
 176  * \return true if so, otherwise false
 177  */
 178 bool ldns_resolver_debug(const ldns_resolver *r);
 179
 180 /**
 181  * Get the number of retries
 182  * \param[in] r the resolver
 183  * \return the number of retries
 184  */
 185 uint8_t ldns_resolver_retry(const ldns_resolver *r);
 186
 187 /**
 188  * Get the retransmit interval
 189  * \param[in] r the resolver
 190  * \return the retransmit interval
 191  */
 192 uint8_t ldns_resolver_retrans(const ldns_resolver *r);
 193
 194 /**
 195  * Get the truncation fallback status
 196  * \param[in] r the resolver
 197  * \return whether the truncation fallback mechanism is used
 198  */
 199 bool ldns_resolver_fallback(const ldns_resolver *r);
 200
 201 /**
 202  * Does the resolver use ip6 or ip4
 203  * \param[in] r the resolver
 204  * \return 0: both, 1: ip4, 2:ip6
 205  */
 206 uint8_t ldns_resolver_ip6(const ldns_resolver *r);
 207
 208 /**
 209  * Get the resolver's udp size
 210  * \param[in] r the resolver
 211  * \return the udp mesg size
 212  */
 213 uint16_t ldns_resolver_edns_udp_size(const ldns_resolver *r);
 214 /**
 215  * Does the resolver use tcp or udp
 216  * \param[in] r the resolver
 217  * \return true: tcp, false: udp
 218  */
 219 bool ldns_resolver_usevc(const ldns_resolver *r);
 220 /**
 221  * Does the resolver only try the first nameserver
 222  * \param[in] r the resolver
 223  * \return true: yes, fail, false: no, try the others
 224  */
 225 bool ldns_resolver_fail(const ldns_resolver *r);
 226 /**
 227  * Does the resolver apply default domain name
 228  * \param[in] r the resolver
 229  * \return true: yes, false: no
 230  */
 231 bool ldns_resolver_defnames(const ldns_resolver *r);
 232 /**
 233  * Does the resolver apply search list
 234  * \param[in] r the resolver
 235  * \return true: yes, false: no
 236  */
 237 bool ldns_resolver_dnsrch(const ldns_resolver *r);
 238 /**
 239  * Does the resolver do DNSSEC
 240  * \param[in] r the resolver
 241  * \return true: yes, false: no
 242  */
 243 bool ldns_resolver_dnssec(const ldns_resolver *r);
 244 /**
 245  * Does the resolver set the CD bit
 246  * \param[in] r the resolver
 247  * \return true: yes, false: no
 248  */
 249 bool ldns_resolver_dnssec_cd(const ldns_resolver *r);
 250 /**
 251  * Get the resolver's DNSSEC anchors
 252  * \param[in] r the resolver
 253  * \return an rr_list containg trusted DNSSEC anchors
 254  */
 255 ldns_rr_list * ldns_resolver_dnssec_anchors(const ldns_resolver *r);
 256 /**
 257  * Does the resolver ignore the TC bit (truncated)
 258  * \param[in] r the resolver
 259  * \return true: yes, false: no
 260  */
 261 bool ldns_resolver_igntc(const ldns_resolver *r);
 262 /**
 263  * Does the resolver randomize the nameserver before usage
 264  * \param[in] r the resolver
 265  * \return true: yes, false: no
 266  */
 267 bool ldns_resolver_random(const ldns_resolver *r);
 268 /**
 269  * How many nameserver are configured in the resolver
 270  * \param[in] r the resolver
 271  * \return number of nameservers
 272  */
 273 size_t ldns_resolver_nameserver_count(const ldns_resolver *r);
 274 /**
 275  * What is the default dname to add to relative queries
 276  * \param[in] r the resolver
 277  * \return the dname which is added
 278  */
 279 ldns_rdf *ldns_resolver_domain(const ldns_resolver *r);
 280 /**
 281  * What is the timeout on socket connections
 282  * \param[in] r the resolver
 283  * \return the timeout as struct timeval
 284  */
 285 struct timeval ldns_resolver_timeout(const ldns_resolver *r);
 286 /**
 287  * What is the searchlist as used by the resolver
 288  * \param[in] r the resolver
 289  * \return a ldns_rdf pointer to a list of the addresses
 290  */
 291 ldns_rdf** ldns_resolver_searchlist(const ldns_resolver *r);
 292 /**
 293  * Return the configured nameserver ip address
 294  * \param[in] r the resolver
 295  * \return a ldns_rdf pointer to a list of the addresses
 296  */
 297 ldns_rdf** ldns_resolver_nameservers(const ldns_resolver *r);
 298 /**
 299  * Return the used round trip times for the nameservers
 300  * \param[in] r the resolver
 301  * \return a size_t* pointer to the list.
 302  * yet)
 303  */
 304 size_t * ldns_resolver_rtt(const ldns_resolver *r);
 305 /**
 306  * Return the used round trip time for a specific nameserver
 307  * \param[in] r the resolver
 308  * \param[in] pos the index to the nameserver
 309  * \return the rrt, 0: infinite, >0: undefined (as of * yet)
 310  */
 311 size_t ldns_resolver_nameserver_rtt(const ldns_resolver *r, size_t pos);
 312 /**
 313  * Return the tsig keyname as used by the nameserver
 314  * \param[in] r the resolver
 315  * \return the name used. Still owned by the resolver - change using
 316  * ldns_resolver_set_tsig_keyname().
 317  */
 318 const char *ldns_resolver_tsig_keyname(const ldns_resolver *r);
 319 /**
 320  * Return the tsig algorithm as used by the nameserver
 321  * \param[in] r the resolver
 322  * \return the algorithm used. Still owned by the resolver - change using
 323  * ldns_resolver_set_tsig_algorithm().
 324  */
 325 const char *ldns_resolver_tsig_algorithm(const ldns_resolver *r);
 326 /**
 327  * Return the tsig keydata as used by the nameserver
 328  * \param[in] r the resolver
 329  * \return the keydata used. Still owned by the resolver - change using
 330  * ldns_resolver_set_tsig_keydata().
 331  */
 332 const char *ldns_resolver_tsig_keydata(const ldns_resolver *r);
 333 /**
 334  * pop the last nameserver from the resolver.
 335  * \param[in] r the resolver
 336  * \return the popped address or NULL if empty
 337  */
 338 ldns_rdf* ldns_resolver_pop_nameserver(ldns_resolver *r);
 339
 340 /**
 341  * Return the resolver's searchlist count
 342  * \param[in] r the resolver
 343  * \return the searchlist count
 344  */
 345 size_t ldns_resolver_searchlist_count(const ldns_resolver *r);
 346
 347 /* write access function */
 348 /**
 349  * Set the port the resolver should use
 350  * \param[in] r the resolver
 351  * \param[in] p the port number
 352  */
 353 void ldns_resolver_set_port(ldns_resolver *r, uint16_t p);
 354
 355 /**
 356  * Set the source rdf (address) the resolver should use
 357  * \param[in] r the resolver
 358  * \param[in] s the source address
 359  */
 360 void ldns_resolver_set_source(ldns_resolver *r, ldns_rdf *s);
 361
 362 /**
 363  * Set the resolver recursion
 364  * \param[in] r the resolver
 365  * \param[in] b true: set to recurse, false: unset
 366  */
 367 void ldns_resolver_set_recursive(ldns_resolver *r, bool b);
 368
 369 /**
 370  * Set the resolver debugging
 371  * \param[in] r the resolver
 372  * \param[in] b true: debug on: false debug off
 373  */
 374 void ldns_resolver_set_debug(ldns_resolver *r, bool b);
 375
 376 /**
 377  * Incremental the resolver's nameserver count.
 378  * \param[in] r the resolver
 379  */
 380 void ldns_resolver_incr_nameserver_count(ldns_resolver *r);
 381
 382 /**
 383  * Decrement the resolver's nameserver count.
 384  * \param[in] r the resolver
 385  */
 386 void ldns_resolver_dec_nameserver_count(ldns_resolver *r);
 387
 388 /**
 389  * Set the resolver's nameserver count directly.
 390  * \param[in] r the resolver
 391  * \param[in] c the nameserver count
 392  */
 393 void ldns_resolver_set_nameserver_count(ldns_resolver *r, size_t c);
 394
 395 /**
 396  * Set the resolver's nameserver count directly by using an rdf list
 397  * \param[in] r the resolver
 398  * \param[in] rd the resolver addresses
 399  */
 400 void ldns_resolver_set_nameservers(ldns_resolver *r, ldns_rdf **rd);
 401
 402 /**
 403  * Set the resolver's default domain. This gets appended when no
 404  * absolute name is given
 405  * \param[in] r the resolver
 406  * \param[in] rd the name to append
 407  */
 408 void ldns_resolver_set_domain(ldns_resolver *r, ldns_rdf *rd);
 409
 410 /**
 411  * Set the resolver's socket time out when talking to remote hosts
 412  * \param[in] r the resolver
 413  * \param[in] timeout the timeout to use
 414  */
 415 void ldns_resolver_set_timeout(ldns_resolver *r, struct timeval timeout);
 416
 417 /**
 418  * Push a new rd to the resolver's searchlist
 419  * \param[in] r the resolver
 420  * \param[in] rd to push
 421  */
 422 void ldns_resolver_push_searchlist(ldns_resolver *r, ldns_rdf *rd);
 423
 424 /**
 425  * Whether the resolver uses the name set with _set_domain
 426  * \param[in] r the resolver
 427  * \param[in] b true: use the defaults, false: don't use them
 428  */
 429 void ldns_resolver_set_defnames(ldns_resolver *r, bool b);
 430
 431 /**
 432  * Whether the resolver uses a virtual circuit (TCP)
 433  * \param[in] r the resolver
 434  * \param[in] b true: use TCP, false: don't use TCP
 435  */
 436 void ldns_resolver_set_usevc(ldns_resolver *r, bool b);
 437
 438 /**
 439  * Whether the resolver uses the searchlist
 440  * \param[in] r the resolver
 441  * \param[in] b true: use the list, false: don't use the list
 442  */
 443 void ldns_resolver_set_dnsrch(ldns_resolver *r, bool b);
 444
 445 /**
 446  * Whether the resolver uses DNSSEC
 447  * \param[in] r the resolver
 448  * \param[in] b true: use DNSSEC, false: don't use DNSSEC
 449  */
 450 void ldns_resolver_set_dnssec(ldns_resolver *r, bool b);
 451
 452 /**
 453  * Whether the resolver uses the checking disable bit
 454  * \param[in] r the resolver
 455  * \param[in] b true: enable , false: don't use TCP
 456  */
 457 void ldns_resolver_set_dnssec_cd(ldns_resolver *r, bool b);
 458 /**
 459  * Set the resolver's DNSSEC anchor list directly. RRs should be of type DS or DNSKEY.
 460  * \param[in] r the resolver
 461  * \param[in] l the list of RRs to use as trust anchors
 462  */
 463 void ldns_resolver_set_dnssec_anchors(ldns_resolver *r, ldns_rr_list * l);
 464
 465 /**
 466  * Push a new trust anchor to the resolver. It must be a DS or DNSKEY rr
 467  * \param[in] r the resolver.
 468  * \param[in] rr the RR to add as a trust anchor.
 469  * \return a status
 470  */
 471 ldns_status ldns_resolver_push_dnssec_anchor(ldns_resolver *r, ldns_rr *rr);
 472
 473 /**
 474  * Set the resolver retrans timeout (in seconds)
 475  * \param[in] r the resolver
 476  * \param[in] re the retransmission interval in seconds
 477  */
 478 void ldns_resolver_set_retrans(ldns_resolver *r, uint8_t re);
 479
 480 /**
 481  * Set whether the resolvers truncation fallback mechanism is used
 482  * when ldns_resolver_query() is called.
 483  * \param[in] r the resolver
 484  * \param[in] fallback whether to use the fallback mechanism
 485  */
 486 void ldns_resolver_set_fallback(ldns_resolver *r, bool fallback);
 487
 488 /**
 489  * Set the number of times a resolver should retry a nameserver before the
 490  * next one is tried.
 491  * \param[in] r the resolver
 492  * \param[in] re the number of retries
 493  */
 494 void ldns_resolver_set_retry(ldns_resolver *r, uint8_t re);
 495
 496 /**
 497  * Whether the resolver uses ip6
 498  * \param[in] r the resolver
 499  * \param[in] i 0: no pref, 1: ip4, 2: ip6
 500  */
 501 void ldns_resolver_set_ip6(ldns_resolver *r, uint8_t i);
 502
 503 /**
 504  * Whether or not to fail after one failed query
 505  * \param[in] r the resolver
 506  * \param[in] b true: yes fail, false: continue with next nameserver
 507  */
 508 void ldns_resolver_set_fail(ldns_resolver *r, bool b);
 509
 510 /**
 511  * Whether or not to ignore the TC bit
 512  * \param[in] r the resolver
 513  * \param[in] b true: yes ignore, false: don't ignore
 514  */
 515 void ldns_resolver_set_igntc(ldns_resolver *r, bool b);
 516
 517 /**
 518  * Set maximum udp size
 519  * \param[in] r the resolver
 520  * \param[in] s the udp max size
 521  */
 522 void ldns_resolver_set_edns_udp_size(ldns_resolver *r, uint16_t s);
 523
 524 /**
 525  * Set the tsig key name
 526  * \param[in] r the resolver
 527  * \param[in] tsig_keyname the tsig key name (copied into resolver)
 528  */
 529 void ldns_resolver_set_tsig_keyname(ldns_resolver *r, const char *tsig_keyname);
 530
 531 /**
 532  * Set the tsig algorithm
 533  * \param[in] r the resolver
 534  * \param[in] tsig_algorithm the tsig algorithm (copied into resolver)
 535  */
 536 void ldns_resolver_set_tsig_algorithm(ldns_resolver *r, const char *tsig_algorithm);
 537
 538 /**
 539  * Set the tsig key data
 540  * \param[in] r the resolver
 541  * \param[in] tsig_keydata the key data (copied into resolver)
 542  */
 543 void ldns_resolver_set_tsig_keydata(ldns_resolver *r, const char *tsig_keydata);
 544
 545 /**
 546  * Set round trip time for all nameservers. Note this currently
 547  * differentiates between: unreachable and reachable.
 548  * \param[in] r the resolver
 549  * \param[in] rtt a list with the times
 550  */
 551 void ldns_resolver_set_rtt(ldns_resolver *r, size_t *rtt);
 552
 553 /**
 554  * Set round trip time for a specific nameserver. Note this
 555  * currently differentiates between: unreachable and reachable.
 556  * \param[in] r the resolver
 557  * \param[in] pos the nameserver position
 558  * \param[in] value the rtt
 559  */
 560 void ldns_resolver_set_nameserver_rtt(ldns_resolver *r, size_t pos, size_t value);
 561
 562 /**
 563  * Should the nameserver list be randomized before each use
 564  * \param[in] r the resolver
 565  * \param[in] b: true: randomize, false: don't
 566  */
 567 void ldns_resolver_set_random(ldns_resolver *r, bool b);
 568
 569 /**
 570  * Push a new nameserver to the resolver. It must be an IP
 571  * address v4 or v6.
 572  * \param[in] r the resolver
 573  * \param[in] n the ip address
 574  * \return ldns_status a status
 575  */
 576 ldns_status ldns_resolver_push_nameserver(ldns_resolver *r, const ldns_rdf *n);
 577
 578 /**
 579  * Push a new nameserver to the resolver. It must be an
 580  * A or AAAA RR record type
 581  * \param[in] r the resolver
 582  * \param[in] rr the resource record
 583  * \return ldns_status a status
 584  */
 585 ldns_status ldns_resolver_push_nameserver_rr(ldns_resolver *r, const ldns_rr *rr);
 586
 587 /**
 588  * Push a new nameserver rr_list to the resolver.
 589  * \param[in] r the resolver
 590  * \param[in] rrlist the rr_list to push
 591  * \return ldns_status a status
 592  */
 593 ldns_status ldns_resolver_push_nameserver_rr_list(ldns_resolver *r, const ldns_rr_list *rrlist);
 594
 595 /**
 596  * Send the query for using the resolver and take the search list into account
 597  * The search algorithm is as follows:
 598  * If the name is absolute, try it as-is, otherwise apply the search list
 599  * \param[in] *r operate using this resolver
 600  * \param[in] *rdf query for this name
 601  * \param[in] t query for this type (may be 0, defaults to A)
 602  * \param[in] c query for this class (may be 0, default to IN)
 603  * \param[in] flags the query flags
 604  *
 605  * \return ldns_pkt* a packet with the reply from the nameserver
 606  */
 607 ldns_pkt* ldns_resolver_search(const ldns_resolver *r, const ldns_rdf *rdf, ldns_rr_type t, ldns_rr_class c, uint16_t flags);
 608
 609
 610 /**
 611  * Send the query for using the resolver and take the search list into account
 612  * The search algorithm is as follows:
 613  * If the name is absolute, try it as-is, otherwise apply the search list
 614  * \param[out] pkt a packet with the reply from the nameserver
 615  * \param[in] *r operate using this resolver
 616  * \param[in] *rdf query for this name
 617  * \param[in] t query for this type (may be 0, defaults to A)
 618  * \param[in] c query for this class (may be 0, default to IN)
 619  * \param[in] flags the query flags
 620  *
 621  * \return ldns_status LDNS_STATUS_OK on success
 622  */
 623 ldns_status ldns_resolver_search_status(ldns_pkt** pkt, ldns_resolver *r, const ldns_rdf *rdf, ldns_rr_type t, ldns_rr_class c, uint16_t flags);
 624
 625 /**
 626  * Form a query packet from a resolver and name/type/class combo
 627  * \param[out] **q a pointer to a ldns_pkt pointer (initialized by this function)
 628  * \param[in] *r operate using this resolver
 629  * \param[in] *name query for this name
 630  * \param[in] t query for this type (may be 0, defaults to A)
 631  * \param[in] c query for this class (may be 0, default to IN)
 632  * \param[in] f the query flags
 633  *
 634  * \return ldns_pkt* a packet with the reply from the nameserver
 635  */
 636 ldns_status ldns_resolver_prepare_query_pkt(ldns_pkt **q, ldns_resolver *r, const  ldns_rdf *name, ldns_rr_type t, ldns_rr_class c, uint16_t f);
 637
 638 /**
 639  * Send the query for name as-is
 640  * \param[out] **answer a pointer to a ldns_pkt pointer (initialized by this function)
 641  * \param[in] *r operate using this resolver
 642  * \param[in] *name query for this name
 643  * \param[in] t query for this type (may be 0, defaults to A)
 644  * \param[in] c query for this class (may be 0, default to IN)
 645  * \param[in] flags the query flags
 646  *
 647  * \return ldns_status LDNS_STATUS_OK on success
 648  */
 649 ldns_status ldns_resolver_send(ldns_pkt **answer, ldns_resolver *r, const ldns_rdf *name, ldns_rr_type t, ldns_rr_class c, uint16_t flags);
 650
 651 /**
 652  * Send the given packet to a nameserver
 653  * \param[out] **answer a pointer to a ldns_pkt pointer (initialized by this function)
 654  * \param[in] *r operate using this resolver
 655  * \param[in] *query_pkt query
 656  */
 657 ldns_status ldns_resolver_send_pkt(ldns_pkt **answer, ldns_resolver *r, ldns_pkt *query_pkt);
 658
 659 /**
 660  * Send a query to a nameserver
 661  * \param[out] pkt a packet with the reply from the nameserver
 662  * \param[in] *r operate using this resolver
 663  * \param[in] *name query for this name
 664  * \param[in] *t query for this type (may be 0, defaults to A)
 665  * \param[in] *c query for this class (may be 0, default to IN)
 666  * \param[in] flags the query flags
 667  *
 668  * \return ldns_status LDNS_STATUS_OK on success
 669  * if _defnames is true the default domain will be added
 670  */
 671 ldns_status ldns_resolver_query_status(ldns_pkt** pkt, ldns_resolver *r, const ldns_rdf *name, ldns_rr_type t, ldns_rr_class c, uint16_t flags);
 672
 673
 674 /**
 675  * Send a query to a nameserver
 676  * \param[in] *r operate using this resolver
 677  *               (despite the const in the declaration,
 678  *                the struct is altered as a side-effect)
 679  * \param[in] *name query for this name
 680  * \param[in] *t query for this type (may be 0, defaults to A)
 681  * \param[in] *c query for this class (may be 0, default to IN)
 682  * \param[in] flags the query flags
 683  *
 684  * \return ldns_pkt* a packet with the reply from the nameserver
 685  * if _defnames is true the default domain will be added
 686  */
 687 ldns_pkt* ldns_resolver_query(const ldns_resolver *r, const ldns_rdf *name, ldns_rr_type t, ldns_rr_class c, uint16_t flags);
 688
 689
 690 /**
 691  * Create a new resolver structure
 692  * \return ldns_resolver* pointer to new structure
 693  */
 694 ldns_resolver* ldns_resolver_new(void);
 695
 696 /**
 697  * Clone a resolver
 698  * \param[in] r the resolver to clone
 699  * \return ldns_resolver* pointer to new structure
 700  */
 701 ldns_resolver* ldns_resolver_clone(ldns_resolver *r);
 702
 703 /**
 704  * Create a resolver structure from a file like /etc/resolv.conf
 705  * \param[out] r the new resolver
 706  * \param[in] fp file pointer to create new resolver from
 707  *      if NULL use /etc/resolv.conf
 708  * \return LDNS_STATUS_OK or the error
 709  */
 710 ldns_status ldns_resolver_new_frm_fp(ldns_resolver **r, FILE *fp);
 711
 712 /**
 713  * Create a resolver structure from a file like /etc/resolv.conf
 714  * \param[out] r the new resolver
 715  * \param[in] fp file pointer to create new resolver from
 716  *      if NULL use /etc/resolv.conf
 717  * \param[in] line_nr pointer to an integer containing the current line number (for debugging purposes)
 718  * \return LDNS_STATUS_OK or the error
 719  */
 720 ldns_status ldns_resolver_new_frm_fp_l(ldns_resolver **r, FILE *fp, int *line_nr);
 721
 722 /**
 723  * Configure a resolver by means of a resolv.conf file
 724  * The file may be NULL in which case there will  be
 725  * looked the RESOLV_CONF (defaults to /etc/resolv.conf)
 726  * \param[out] r the new resolver
 727  * \param[in] filename the filename to use
 728  * \return LDNS_STATUS_OK or the error
 729  */
 730 ldns_status ldns_resolver_new_frm_file(ldns_resolver **r, const char *filename);
 731
 732 /**
 733  * Frees the allocated space for this resolver. Only frees the resolver pionter! You should probably be using _deep_free.
 734  * \param res resolver to free
 735  */
 736 void ldns_resolver_free(ldns_resolver *res);
 737
 738 /**
 739  * Frees the allocated space for this resolver and all it's data
 740  * \param res resolver to free
 741  */
 742 void ldns_resolver_deep_free(ldns_resolver *res);
 743
 744 /**
 745  * Get the next stream of RRs in a AXFR
 746  * \param[in] resolver the resolver to use. First ldns_axfr_start() must be
 747  * called
 748  * \return ldns_rr the next RR from the AXFR stream
 749  * After you get this returned RR (not NULL: on error), then check if
 750  * ldns_axfr_complete() is true to see if the zone transfer has completed.
 751  */
 752 ldns_rr* ldns_axfr_next(ldns_resolver *resolver);
 753
 754 /**
 755  * Abort a transfer that is in progress
 756  * \param[in] resolver the resolver that is used
 757  */
 758 void ldns_axfr_abort(ldns_resolver *resolver);
 759
 760 /**
 761  * Returns true if the axfr transfer has completed (i.e. 2 SOA RRs and no errors were encountered
 762  * \param[in] resolver the resolver that is used
 763  * \return bool true if axfr transfer was completed without error
 764  */
 765 bool ldns_axfr_complete(const ldns_resolver *resolver);
 766
 767 /**
 768  * Returns a pointer to the last ldns_pkt that was sent by the server in the AXFR transfer
 769  * uasable for instance to get the error code on failure
 770  * \param[in] res the resolver that was used in the axfr transfer
 771  * \return ldns_pkt the last packet sent
 772  */
 773 ldns_pkt *ldns_axfr_last_pkt(const ldns_resolver *res);
 774
 775 /**
 776  * Get the serial for requesting IXFR.
 777  * \param[in] r the resolver
 778  * \param[in] serial serial
 779  */
 780 void ldns_resolver_set_ixfr_serial(ldns_resolver *r, uint32_t serial);
 781
 782 /**
 783  * Get the serial for requesting IXFR.
 784  * \param[in] res the resolver
 785  * \return uint32_t serial
 786  */
 787 uint32_t ldns_resolver_get_ixfr_serial(const ldns_resolver *res);
 788
 789 /**
 790  * Randomize the nameserver list in the resolver
 791  * \param[in] r the resolver
 792  */
 793 void ldns_resolver_nameservers_randomize(ldns_resolver *r);
 794
 795 /**
 796  * Returns true if at least one of the provided keys is a trust anchor
 797  * \param[in] r the current resolver
 798  * \param[in] keys the keyset to check
 799  * \param[out] trusted_keys the subset of trusted keys in the 'keys' rrset
 800  * \return true if at least one of the provided keys is a configured trust anchor
 801  */
 802 bool ldns_resolver_trusted_key(const ldns_resolver *r, ldns_rr_list * keys, ldns_rr_list * trusted_keys);
 803
 804 #ifdef __cplusplus
 805 }
 806 #endif
 807
 808 #endif  /* LDNS_RESOLVER_H */