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