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         /**  Wether 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
 132         /* Optional tsig key for signing queries,
 133         outgoing messages are signed if and only if both are set
 134         */
 135         /** Name of the key to use with TSIG, if _tsig_keyname and _tsig_keydata both contain values, outgoing messages are automatically signed with TSIG. */
 136         char *_tsig_keyname;
 137         /** Secret key data to use with TSIG, if _tsig_keyname and _tsig_keydata both contain values, outgoing messages are automatically signed with TSIG. */
 138         char *_tsig_keydata;
 139         /** TSIG signing algorithm */
 140         char *_tsig_algorithm;
 141
 142         /** Source address to query from */
 143         ldns_rdf *_source;
 144 };
 145 typedef struct ldns_struct_resolver ldns_resolver;
 146
 147 /* prototypes */
 148 /* read access functions */
 149
 150 /**
 151  * Get the port the resolver should use
 152  * \param[in] r the resolver
 153  * \return the port number
 154  */
 155 uint16_t ldns_resolver_port(const ldns_resolver *r);
 156
 157 /**
 158  * Get the source address the resolver should use
 159  * \param[in] r the resolver
 160  * \return the source rdf
 161  */
 162 ldns_rdf *ldns_resolver_source(const ldns_resolver *r);
 163
 164 /**
 165  * Is the resolver set to recurse
 166  * \param[in] r the resolver
 167  * \return true if so, otherwise false
 168  */
 169 bool ldns_resolver_recursive(const ldns_resolver *r);
 170
 171 /**
 172  * Get the debug status of the resolver
 173  * \param[in] r the resolver
 174  * \return true if so, otherwise false
 175  */
 176 bool ldns_resolver_debug(const ldns_resolver *r);
 177
 178 /**
 179  * Get the number of retries
 180  * \param[in] r the resolver
 181  * \return the number of retries
 182  */
 183 uint8_t ldns_resolver_retry(const ldns_resolver *r);
 184
 185 /**
 186  * Get the retransmit interval
 187  * \param[in] r the resolver
 188  * \return the retransmit interval
 189  */
 190 uint8_t ldns_resolver_retrans(const ldns_resolver *r);
 191
 192 /**
 193  * Get the truncation fallback status
 194  * \param[in] r the resolver
 195  * \return whether the truncation fallback mechanism is used
 196  */
 197 bool ldns_resolver_fallback(const ldns_resolver *r);
 198
 199 /**
 200  * Does the resolver use ip6 or ip4
 201  * \param[in] r the resolver
 202  * \return 0: both, 1: ip4, 2:ip6
 203  */
 204 uint8_t ldns_resolver_ip6(const ldns_resolver *r);
 205
 206 /**
 207  * Get the resolver's udp size
 208  * \param[in] r the resolver
 209  * \return the udp mesg size
 210  */
 211 uint16_t ldns_resolver_edns_udp_size(const ldns_resolver *r);
 212 /**
 213  * Does the resolver use tcp or udp
 214  * \param[in] r the resolver
 215  * \return true: tcp, false: udp
 216  */
 217 bool ldns_resolver_usevc(const ldns_resolver *r);
 218 /**
 219  * Does the resolver only try the first nameserver
 220  * \param[in] r the resolver
 221  * \return true: yes, fail, false: no, try the others
 222  */
 223 bool ldns_resolver_fail(const ldns_resolver *r);
 224 /**
 225  * Does the resolver apply default domain name
 226  * \param[in] r the resolver
 227  * \return true: yes, false: no
 228  */
 229 bool ldns_resolver_defnames(const ldns_resolver *r);
 230 /**
 231  * Does the resolver apply search list
 232  * \param[in] r the resolver
 233  * \return true: yes, false: no
 234  */
 235 bool ldns_resolver_dnsrch(const ldns_resolver *r);
 236 /**
 237  * Does the resolver do DNSSEC
 238  * \param[in] r the resolver
 239  * \return true: yes, false: no
 240  */
 241 bool ldns_resolver_dnssec(const ldns_resolver *r);
 242 /**
 243  * Does the resolver set the CD bit
 244  * \param[in] r the resolver
 245  * \return true: yes, false: no
 246  */
 247 bool ldns_resolver_dnssec_cd(const ldns_resolver *r);
 248 /**
 249  * Get the resolver's DNSSEC anchors
 250  * \param[in] r the resolver
 251  * \return an rr_list containg trusted DNSSEC anchors
 252  */
 253 ldns_rr_list * ldns_resolver_dnssec_anchors(const ldns_resolver *r);
 254 /**
 255  * Does the resolver ignore the TC bit (truncated)
 256  * \param[in] r the resolver
 257  * \return true: yes, false: no
 258  */
 259 bool ldns_resolver_igntc(const ldns_resolver *r);
 260 /**
 261  * Does the resolver randomize the nameserver before usage
 262  * \param[in] r the resolver
 263  * \return true: yes, false: no
 264  */
 265 bool ldns_resolver_random(const ldns_resolver *r);
 266 /**
 267  * How many nameserver are configured in the resolver
 268  * \param[in] r the resolver
 269  * \return number of nameservers
 270  */
 271 size_t ldns_resolver_nameserver_count(const ldns_resolver *r);
 272 /**
 273  * What is the default dname to add to relative queries
 274  * \param[in] r the resolver
 275  * \return the dname which is added
 276  */
 277 ldns_rdf *ldns_resolver_domain(const ldns_resolver *r);
 278 /**
 279  * What is the timeout on socket connections
 280  * \param[in] r the resolver
 281  * \return the timeout as struct timeval
 282  */
 283 struct timeval ldns_resolver_timeout(const ldns_resolver *r);
 284 /**
 285  * What is the searchlist as used by the resolver
 286  * \param[in] r the resolver
 287  * \return a ldns_rdf pointer to a list of the addresses
 288  */
 289 ldns_rdf** ldns_resolver_searchlist(const ldns_resolver *r);
 290 /**
 291  * Return the configured nameserver ip address
 292  * \param[in] r the resolver
 293  * \return a ldns_rdf pointer to a list of the addresses
 294  */
 295 ldns_rdf** ldns_resolver_nameservers(const ldns_resolver *r);
 296 /**
 297  * Return the used round trip times for the nameservers
 298  * \param[in] r the resolver
 299  * \return a size_t* pointer to the list.
 300  * yet)
 301  */
 302 size_t * ldns_resolver_rtt(const ldns_resolver *r);
 303 /**
 304  * Return the used round trip time for a specific nameserver
 305  * \param[in] r the resolver
 306  * \param[in] pos the index to the nameserver
 307  * \return the rrt, 0: infinite, >0: undefined (as of * yet)
 308  */
 309 size_t ldns_resolver_nameserver_rtt(const ldns_resolver *r, size_t pos);
 310 /**
 311  * Return the tsig keyname as used by the nameserver
 312  * \param[in] r the resolver
 313  * \return the name used.
 314  */
 315 char *ldns_resolver_tsig_keyname(const ldns_resolver *r);
 316 /**
 317  * Return the tsig algorithm as used by the nameserver
 318  * \param[in] r the resolver
 319  * \return the algorithm used.
 320  */
 321 char *ldns_resolver_tsig_algorithm(const ldns_resolver *r);
 322 /**
 323  * Return the tsig keydata as used by the nameserver
 324  * \param[in] r the resolver
 325  * \return the keydata used.
 326  */
 327 char *ldns_resolver_tsig_keydata(const ldns_resolver *r);
 328 /**
 329  * pop the last nameserver from the resolver.
 330  * \param[in] r the resolver
 331  * \return the popped address or NULL if empty
 332  */
 333 ldns_rdf* ldns_resolver_pop_nameserver(ldns_resolver *r);
 334
 335 /**
 336  * Return the resolver's searchlist count
 337  * \param[in] r the resolver
 338  * \return the searchlist count
 339  */
 340 size_t ldns_resolver_searchlist_count(const ldns_resolver *r);
 341
 342 /* write access function */
 343 /**
 344  * Set the port the resolver should use
 345  * \param[in] r the resolver
 346  * \param[in] p the port number
 347  */
 348 void ldns_resolver_set_port(ldns_resolver *r, uint16_t p);
 349
 350 /**
 351  * Set the source rdf (address) the resolver should use
 352  * \param[in] r the resolver
 353  * \param[in] s the source address
 354  */
 355 void ldns_resolver_set_source(ldns_resolver *r, ldns_rdf *s);
 356
 357 /**
 358  * Set the resolver recursion
 359  * \param[in] r the resolver
 360  * \param[in] b true: set to recurse, false: unset
 361  */
 362 void ldns_resolver_set_recursive(ldns_resolver *r, bool b);
 363
 364 /**
 365  * Set the resolver debugging
 366  * \param[in] r the resolver
 367  * \param[in] b true: debug on: false debug off
 368  */
 369 void ldns_resolver_set_debug(ldns_resolver *r, bool b);
 370
 371 /**
 372  * Incremental the resolver's nameserver count.
 373  * \param[in] r the resolver
 374  */
 375 void ldns_resolver_incr_nameserver_count(ldns_resolver *r);
 376
 377 /**
 378  * Decrement the resolver's nameserver count.
 379  * \param[in] r the resolver
 380  */
 381 void ldns_resolver_dec_nameserver_count(ldns_resolver *r);
 382
 383 /**
 384  * Set the resolver's nameserver count directly.
 385  * \param[in] r the resolver
 386  * \param[in] c the nameserver count
 387  */
 388 void ldns_resolver_set_nameserver_count(ldns_resolver *r, size_t c);
 389
 390 /**
 391  * Set the resolver's nameserver count directly by using an rdf list
 392  * \param[in] r the resolver
 393  * \param[in] rd the resolver addresses
 394  */
 395 void ldns_resolver_set_nameservers(ldns_resolver *r, ldns_rdf **rd);
 396
 397 /**
 398  * Set the resolver's default domain. This gets appended when no
 399  * absolute name is given
 400  * \param[in] r the resolver
 401  * \param[in] rd the name to append
 402  */
 403 void ldns_resolver_set_domain(ldns_resolver *r, ldns_rdf *rd);
 404
 405 /**
 406  * Set the resolver's socket time out when talking to remote hosts
 407  * \param[in] r the resolver
 408  * \param[in] timeout the timeout to use
 409  */
 410 void ldns_resolver_set_timeout(ldns_resolver *r, struct timeval timeout);
 411
 412 /**
 413  * Push a new rd to the resolver's searchlist
 414  * \param[in] r the resolver
 415  * \param[in] rd to push
 416  */
 417 void ldns_resolver_push_searchlist(ldns_resolver *r, ldns_rdf *rd);
 418
 419 /**
 420  * Whether the resolver uses the name set with _set_domain
 421  * \param[in] r the resolver
 422  * \param[in] b true: use the defaults, false: don't use them
 423  */
 424 void ldns_resolver_set_defnames(ldns_resolver *r, bool b);
 425
 426 /**
 427  * Whether the resolver uses a virtual circuit (TCP)
 428  * \param[in] r the resolver
 429  * \param[in] b true: use TCP, false: don't use TCP
 430  */
 431 void ldns_resolver_set_usevc(ldns_resolver *r, bool b);
 432
 433 /**
 434  * Whether the resolver uses the searchlist
 435  * \param[in] r the resolver
 436  * \param[in] b true: use the list, false: don't use the list
 437  */
 438 void ldns_resolver_set_dnsrch(ldns_resolver *r, bool b);
 439
 440 /**
 441  * Whether the resolver uses DNSSEC
 442  * \param[in] r the resolver
 443  * \param[in] b true: use DNSSEC, false: don't use DNSSEC
 444  */
 445 void ldns_resolver_set_dnssec(ldns_resolver *r, bool b);
 446
 447 /**
 448  * Whether the resolver uses the checking disable bit
 449  * \param[in] r the resolver
 450  * \param[in] b true: enable , false: don't use TCP
 451  */
 452 void ldns_resolver_set_dnssec_cd(ldns_resolver *r, bool b);
 453 /**
 454  * Set the resolver's DNSSEC anchor list directly. RRs should be of type DS or DNSKEY.
 455  * \param[in] r the resolver
 456  * \param[in] l the list of RRs to use as trust anchors
 457  */
 458 void ldns_resolver_set_dnssec_anchors(ldns_resolver *r, ldns_rr_list * l);
 459
 460 /**
 461  * Push a new trust anchor to the resolver. It must be a DS or DNSKEY rr
 462  * \param[in] r the resolver.
 463  * \param[in] rr the RR to add as a trust anchor.
 464  * \return a status
 465  */
 466 ldns_status ldns_resolver_push_dnssec_anchor(ldns_resolver *r, ldns_rr *rr);
 467
 468 /**
 469  * Set the resolver retrans timeout (in seconds)
 470  * \param[in] r the resolver
 471  * \param[in] re the retransmission interval in seconds
 472  */
 473 void ldns_resolver_set_retrans(ldns_resolver *r, uint8_t re);
 474
 475 /**
 476  * Set whether the resolvers truncation fallback mechanism is used
 477  * when ldns_resolver_query() is called.
 478  * \param[in] r the resolver
 479  * \param[in] fallback whether to use the fallback mechanism
 480  */
 481 void ldns_resolver_set_fallback(ldns_resolver *r, bool fallback);
 482
 483 /**
 484  * Set the number of times a resolver should retry a nameserver before the
 485  * next one is tried.
 486  * \param[in] r the resolver
 487  * \param[in] re the number of retries
 488  */
 489 void ldns_resolver_set_retry(ldns_resolver *r, uint8_t re);
 490
 491 /**
 492  * Whether the resolver uses ip6
 493  * \param[in] r the resolver
 494  * \param[in] i 0: no pref, 1: ip4, 2: ip6
 495  */
 496 void ldns_resolver_set_ip6(ldns_resolver *r, uint8_t i);
 497
 498 /**
 499  * Whether or not to fail after one failed query
 500  * \param[in] r the resolver
 501  * \param[in] b true: yes fail, false: continue with next nameserver
 502  */
 503 void ldns_resolver_set_fail(ldns_resolver *r, bool b);
 504
 505 /**
 506  * Whether or not to ignore the TC bit
 507  * \param[in] r the resolver
 508  * \param[in] b true: yes ignore, false: don't ignore
 509  */
 510 void ldns_resolver_set_igntc(ldns_resolver *r, bool b);
 511
 512 /**
 513  * Set maximum udp size
 514  * \param[in] r the resolver
 515  * \param[in] s the udp max size
 516  */
 517 void ldns_resolver_set_edns_udp_size(ldns_resolver *r, uint16_t s);
 518
 519 /**
 520  * Set the tsig key name
 521  * \param[in] r the resolver
 522  * \param[in] tsig_keyname the tsig key name
 523  */
 524 void ldns_resolver_set_tsig_keyname(ldns_resolver *r, char *tsig_keyname);
 525
 526 /**
 527  * Set the tsig algorithm
 528  * \param[in] r the resolver
 529  * \param[in] tsig_algorithm the tsig algorithm
 530  */
 531 void ldns_resolver_set_tsig_algorithm(ldns_resolver *r, char *tsig_algorithm);
 532
 533 /**
 534  * Set the tsig key data
 535  * \param[in] r the resolver
 536  * \param[in] tsig_keydata the key data
 537  */
 538 void ldns_resolver_set_tsig_keydata(ldns_resolver *r, char *tsig_keydata);
 539
 540 /**
 541  * Set round trip time for all nameservers. Note this currently
 542  * differentiates between: unreachable and reachable.
 543  * \param[in] r the resolver
 544  * \param[in] rtt a list with the times
 545  */
 546 void ldns_resolver_set_rtt(ldns_resolver *r, size_t *rtt);
 547
 548 /**
 549  * Set round trip time for a specific nameserver. Note this
 550  * currently differentiates between: unreachable and reachable.
 551  * \param[in] r the resolver
 552  * \param[in] pos the nameserver position
 553  * \param[in] value the rtt
 554  */
 555 void ldns_resolver_set_nameserver_rtt(ldns_resolver *r, size_t pos, size_t value);
 556
 557 /**
 558  * Should the nameserver list be randomized before each use
 559  * \param[in] r the resolver
 560  * \param[in] b: true: randomize, false: don't
 561  */
 562 void ldns_resolver_set_random(ldns_resolver *r, bool b);
 563
 564 /**
 565  * Push a new nameserver to the resolver. It must be an IP
 566  * address v4 or v6.
 567  * \param[in] r the resolver
 568  * \param[in] n the ip address
 569  * \return ldns_status a status
 570  */
 571 ldns_status ldns_resolver_push_nameserver(ldns_resolver *r, ldns_rdf *n);
 572
 573 /**
 574  * Push a new nameserver to the resolver. It must be an
 575  * A or AAAA RR record type
 576  * \param[in] r the resolver
 577  * \param[in] rr the resource record
 578  * \return ldns_status a status
 579  */
 580 ldns_status ldns_resolver_push_nameserver_rr(ldns_resolver *r, ldns_rr *rr);
 581
 582 /**
 583  * Push a new nameserver rr_list to the resolver.
 584  * \param[in] r the resolver
 585  * \param[in] rrlist the rr_list to push
 586  * \return ldns_status a status
 587  */
 588 ldns_status ldns_resolver_push_nameserver_rr_list(ldns_resolver *r, ldns_rr_list *rrlist);
 589
 590 /**
 591  * Send the query for using the resolver and take the search list into account
 592  * The search algorithm is as follows:
 593  * If the name is absolute, try it as-is, otherwise apply the search list
 594  * \param[in] *r operate using this resolver
 595  * \param[in] *rdf query for this name
 596  * \param[in] t query for this type (may be 0, defaults to A)
 597  * \param[in] c query for this class (may be 0, default to IN)
 598  * \param[in] flags the query flags
 599  *
 600  * \return ldns_pkt* a packet with the reply from the nameserver
 601  */
 602 ldns_pkt* ldns_resolver_search(const ldns_resolver *r, const ldns_rdf *rdf, ldns_rr_type t, ldns_rr_class c, uint16_t flags);
 603
 604
 605 /**
 606  * Send the query for using the resolver and take the search list into account
 607  * The search algorithm is as follows:
 608  * If the name is absolute, try it as-is, otherwise apply the search list
 609  * \param[out] pkt a packet with the reply from the nameserver
 610  * \param[in] *r operate using this resolver
 611  * \param[in] *rdf query for this name
 612  * \param[in] t query for this type (may be 0, defaults to A)
 613  * \param[in] c query for this class (may be 0, default to IN)
 614  * \param[in] flags the query flags
 615  *
 616  * \return ldns_status LDNS_STATUS_OK on success
 617  */
 618 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);
 619
 620 /**
 621  * Form a query packet from a resolver and name/type/class combo
 622  * \param[out] **q a pointer to a ldns_pkt pointer (initialized by this function)
 623  * \param[in] *r operate using this resolver
 624  * \param[in] *name query for this name
 625  * \param[in] t query for this type (may be 0, defaults to A)
 626  * \param[in] c query for this class (may be 0, default to IN)
 627  * \param[in] f the query flags
 628  *
 629  * \return ldns_pkt* a packet with the reply from the nameserver
 630  */
 631 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);
 632
 633 /**
 634  * Send the query for name as-is
 635  * \param[out] **answer a pointer to a ldns_pkt pointer (initialized by this function)
 636  * \param[in] *r operate using this resolver
 637  * \param[in] *name query for this name
 638  * \param[in] t query for this type (may be 0, defaults to A)
 639  * \param[in] c query for this class (may be 0, default to IN)
 640  * \param[in] flags the query flags
 641  *
 642  * \return ldns_pkt* a packet with the reply from the nameserver
 643  */
 644 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);
 645
 646 /**
 647  * Send the given packet to a nameserver
 648  * \param[out] **answer a pointer to a ldns_pkt pointer (initialized by this function)
 649  * \param[in] *r operate using this resolver
 650  * \param[in] *query_pkt query
 651  */
 652 ldns_status ldns_resolver_send_pkt(ldns_pkt **answer, ldns_resolver *r, ldns_pkt *query_pkt);
 653
 654 /**
 655  * Send a query to a nameserver
 656  * \param[out] pkt a packet with the reply from the nameserver
 657  * \param[in] *r operate using this resolver
 658  * \param[in] *name query for this name
 659  * \param[in] *t query for this type (may be 0, defaults to A)
 660  * \param[in] *c query for this class (may be 0, default to IN)
 661  * \param[in] flags the query flags
 662  *
 663  * \return ldns_status LDNS_STATUS_OK on success
 664  * if _defnames is true the default domain will be added
 665  */
 666 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);
 667
 668
 669 /**
 670  * Send a query to a nameserver
 671  * \param[in] *r operate using this resolver
 672  *               (despite the const in the declaration,
 673  *                the struct is altered as a side-effect)
 674  * \param[in] *name query for this name
 675  * \param[in] *t query for this type (may be 0, defaults to A)
 676  * \param[in] *c query for this class (may be 0, default to IN)
 677  * \param[in] flags the query flags
 678  *
 679  * \return ldns_pkt* a packet with the reply from the nameserver
 680  * if _defnames is true the default domain will be added
 681  */
 682 ldns_pkt* ldns_resolver_query(const ldns_resolver *r, const ldns_rdf *name, ldns_rr_type t, ldns_rr_class c, uint16_t flags);
 683
 684
 685 /**
 686  * Create a new resolver structure
 687  * \return ldns_resolver* pointer to new strcture
 688  */
 689 ldns_resolver* ldns_resolver_new(void);
 690
 691 /**
 692  * Create a resolver structure from a file like /etc/resolv.conf
 693  * \param[out] r the new resolver
 694  * \param[in] fp file pointer to create new resolver from
 695  *      if NULL use /etc/resolv.conf
 696  * \return LDNS_STATUS_OK or the error
 697  */
 698 ldns_status ldns_resolver_new_frm_fp(ldns_resolver **r, FILE *fp);
 699
 700 /**
 701  * Create a resolver structure from a file like /etc/resolv.conf
 702  * \param[out] r the new resolver
 703  * \param[in] fp file pointer to create new resolver from
 704  *      if NULL use /etc/resolv.conf
 705  * \param[in] line_nr pointer to an integer containing the current line number (for debugging purposes)
 706  * \return LDNS_STATUS_OK or the error
 707  */
 708 ldns_status ldns_resolver_new_frm_fp_l(ldns_resolver **r, FILE *fp, int *line_nr);
 709
 710 /**
 711  * Configure a resolver by means of a resolv.conf file
 712  * The file may be NULL in which case there will  be
 713  * looked the RESOLV_CONF (defaults to /etc/resolv.conf
 714  * \param[out] r the new resolver
 715  * \param[in] filename the filename to use
 716  * \return LDNS_STATUS_OK or the error
 717  */
 718 ldns_status ldns_resolver_new_frm_file(ldns_resolver **r, const char *filename);
 719
 720 /**
 721  * Frees the allocated space for this resolver. Only frees the resolver pionter! You should probably be using _deep_free.
 722  * \param res resolver to free
 723  */
 724 void ldns_resolver_free(ldns_resolver *res);
 725
 726 /**
 727  * Frees the allocated space for this resolver and all it's data
 728  * \param res resolver to free
 729  */
 730 void ldns_resolver_deep_free(ldns_resolver *res);
 731
 732 /**
 733  * Get the next stream of RRs in a AXFR
 734  * \param[in] resolver the resolver to use. First ldns_axfr_start() must be
 735  * called
 736  * \return ldns_rr the next RR from the AXFR stream
 737  * After you get this returned RR (not NULL: on error), then check if
 738  * ldns_axfr_complete() is true to see if the zone transfer has completed.
 739  */
 740 ldns_rr* ldns_axfr_next(ldns_resolver *resolver);
 741
 742 /**
 743  * Abort a transfer that is in progress
 744  * \param[in] resolver the resolver that is used
 745  */
 746 void ldns_axfr_abort(ldns_resolver *resolver);
 747
 748 /**
 749  * Returns true if the axfr transfer has completed (i.e. 2 SOA RRs and no errors were encountered
 750  * \param[in] resolver the resolver that is used
 751  * \return bool true if axfr transfer was completed without error
 752  */
 753 bool ldns_axfr_complete(const ldns_resolver *resolver);
 754
 755 /**
 756  * Returns a pointer to the last ldns_pkt that was sent by the server in the AXFR transfer
 757  * uasable for instance to get the error code on failure
 758  * \param[in] res the resolver that was used in the axfr transfer
 759  * \return ldns_pkt the last packet sent
 760  */
 761 ldns_pkt *ldns_axfr_last_pkt(const ldns_resolver *res);
 762
 763 /**
 764  * Randomize the nameserver list in the resolver
 765  * \param[in] r the resolver
 766  */
 767 void ldns_resolver_nameservers_randomize(ldns_resolver *r);
 768
 769 /**
 770  * Returns true if at least one of the provided keys is a trust anchor
 771  * \param[in] r the current resolver
 772  * \param[in] keys the keyset to check
 773  * \param[out] trusted_keys the subset of trusted keys in the 'keys' rrset
 774  * \return true if at least one of the provided keys is a configured trust anchor
 775  */
 776 bool ldns_resolver_trusted_key(const ldns_resolver *r, ldns_rr_list * keys, ldns_rr_list * trusted_keys);
 777
 778 #ifdef __cplusplus
 779 }
 780 #endif
 781
 782 #endif  /* LDNS_RESOLVER_H */