contrib/ldns/ldns/rr.h

   1 /*
   2  * rr.h -  resource record definitions
   3  *
   4  * a Net::DNS like library for C
   5  *
   6  * (c) NLnet Labs, 2005-2006
   7  *
   8  * See the file LICENSE for the license
   9  */
  10
  11 /**
  12  * \file
  13  *
  14  * Contains the definition of ldns_rr and functions to manipulate those.
  15  */
  16
  17
  18 #ifndef LDNS_RR_H
  19 #define LDNS_RR_H
  20
  21 #include <ldns/common.h>
  22 #include <ldns/rdata.h>
  23 #include <ldns/buffer.h>
  24 #include <ldns/error.h>
  25
  26 #ifdef __cplusplus
  27 extern "C" {
  28 #endif
  29
  30 /** Maximum length of a dname label */
  31 #define LDNS_MAX_LABELLEN     63
  32 /** Maximum length of a complete dname */
  33 #define LDNS_MAX_DOMAINLEN    255
  34 /** Maximum number of pointers in 1 dname */
  35 #define LDNS_MAX_POINTERS       65535
  36 /** The bytes TTL, CLASS and length use up in an rr */
  37 #define LDNS_RR_OVERHEAD        10
  38
  39 /* The first fields are 'common' and can be referenced instantly */
  40 #define LDNS_RDATA_FIELD_DESCRIPTORS_COMMON 52
  41
  42
  43
  44 /**
  45  *  The different RR classes.
  46  */
  47 enum ldns_enum_rr_class
  48 {
  49         /** the Internet */
  50         LDNS_RR_CLASS_IN        = 1,
  51         /** Chaos class */
  52         LDNS_RR_CLASS_CH        = 3,
  53         /** Hesiod (Dyer 87) */
  54         LDNS_RR_CLASS_HS        = 4,
  55     /** None class, dynamic update */
  56     LDNS_RR_CLASS_NONE      = 254,
  57         /** Any class */
  58         LDNS_RR_CLASS_ANY       = 255,
  59
  60         LDNS_RR_CLASS_FIRST     = 0,
  61         LDNS_RR_CLASS_LAST      = 65535,
  62         LDNS_RR_CLASS_COUNT     = LDNS_RR_CLASS_LAST - LDNS_RR_CLASS_FIRST + 1
  63 };
  64 typedef enum ldns_enum_rr_class ldns_rr_class;
  65
  66 /**
  67  *  Used to specify whether compression is allowed.
  68  */
  69 enum ldns_enum_rr_compress
  70 {
  71         /** compression is allowed */
  72         LDNS_RR_COMPRESS,
  73         LDNS_RR_NO_COMPRESS
  74 };
  75 typedef enum ldns_enum_rr_compress ldns_rr_compress;
  76
  77 /**
  78  * The different RR types.
  79  */
  80 enum ldns_enum_rr_type
  81 {
  82         /**  a host address */
  83         LDNS_RR_TYPE_A = 1,
  84         /**  an authoritative name server */
  85         LDNS_RR_TYPE_NS = 2,
  86         /**  a mail destination (Obsolete - use MX) */
  87         LDNS_RR_TYPE_MD = 3,
  88         /**  a mail forwarder (Obsolete - use MX) */
  89         LDNS_RR_TYPE_MF = 4,
  90         /**  the canonical name for an alias */
  91         LDNS_RR_TYPE_CNAME = 5,
  92         /**  marks the start of a zone of authority */
  93         LDNS_RR_TYPE_SOA = 6,
  94         /**  a mailbox domain name (EXPERIMENTAL) */
  95         LDNS_RR_TYPE_MB = 7,
  96         /**  a mail group member (EXPERIMENTAL) */
  97         LDNS_RR_TYPE_MG = 8,
  98         /**  a mail rename domain name (EXPERIMENTAL) */
  99         LDNS_RR_TYPE_MR = 9,
 100         /**  a null RR (EXPERIMENTAL) */
 101         LDNS_RR_TYPE_NULL = 10,
 102         /**  a well known service description */
 103         LDNS_RR_TYPE_WKS = 11,
 104         /**  a domain name pointer */
 105         LDNS_RR_TYPE_PTR = 12,
 106         /**  host information */
 107         LDNS_RR_TYPE_HINFO = 13,
 108         /**  mailbox or mail list information */
 109         LDNS_RR_TYPE_MINFO = 14,
 110         /**  mail exchange */
 111         LDNS_RR_TYPE_MX = 15,
 112         /**  text strings */
 113         LDNS_RR_TYPE_TXT = 16,
 114         /**  RFC1183 */
 115         LDNS_RR_TYPE_RP = 17,
 116         /**  RFC1183 */
 117         LDNS_RR_TYPE_AFSDB = 18,
 118         /**  RFC1183 */
 119         LDNS_RR_TYPE_X25 = 19,
 120         /**  RFC1183 */
 121         LDNS_RR_TYPE_ISDN = 20,
 122         /**  RFC1183 */
 123         LDNS_RR_TYPE_RT = 21,
 124         /**  RFC1706 */
 125         LDNS_RR_TYPE_NSAP = 22,
 126         /**  RFC1348 */
 127         LDNS_RR_TYPE_NSAP_PTR = 23,
 128         /**  2535typecode */
 129         LDNS_RR_TYPE_SIG = 24,
 130         /**  2535typecode */
 131         LDNS_RR_TYPE_KEY = 25,
 132         /**  RFC2163 */
 133         LDNS_RR_TYPE_PX = 26,
 134         /**  RFC1712 */
 135         LDNS_RR_TYPE_GPOS = 27,
 136         /**  ipv6 address */
 137         LDNS_RR_TYPE_AAAA = 28,
 138         /**  LOC record  RFC1876 */
 139         LDNS_RR_TYPE_LOC = 29,
 140         /**  2535typecode */
 141         LDNS_RR_TYPE_NXT = 30,
 142         /**  draft-ietf-nimrod-dns-01.txt */
 143         LDNS_RR_TYPE_EID = 31,
 144         /**  draft-ietf-nimrod-dns-01.txt */
 145         LDNS_RR_TYPE_NIMLOC = 32,
 146         /**  SRV record RFC2782 */
 147         LDNS_RR_TYPE_SRV = 33,
 148         /**  http://www.jhsoft.com/rfc/af-saa-0069.000.rtf */
 149         LDNS_RR_TYPE_ATMA = 34,
 150         /**  RFC2915 */
 151         LDNS_RR_TYPE_NAPTR = 35,
 152         /**  RFC2230 */
 153         LDNS_RR_TYPE_KX = 36,
 154         /**  RFC2538 */
 155         LDNS_RR_TYPE_CERT = 37,
 156         /**  RFC2874 */
 157         LDNS_RR_TYPE_A6 = 38,
 158         /**  RFC2672 */
 159         LDNS_RR_TYPE_DNAME = 39,
 160         /**  dnsind-kitchen-sink-02.txt */
 161         LDNS_RR_TYPE_SINK = 40,
 162         /**  Pseudo OPT record... */
 163         LDNS_RR_TYPE_OPT = 41,
 164         /**  RFC3123 */
 165         LDNS_RR_TYPE_APL = 42,
 166         /**  draft-ietf-dnsext-delegation */
 167         LDNS_RR_TYPE_DS = 43,
 168         /**  SSH Key Fingerprint */
 169         LDNS_RR_TYPE_SSHFP = 44,
 170         /**  draft-richardson-ipseckey-rr-11.txt */
 171         LDNS_RR_TYPE_IPSECKEY = 45,
 172         /**  draft-ietf-dnsext-dnssec-25 */
 173         LDNS_RR_TYPE_RRSIG = 46,
 174         LDNS_RR_TYPE_NSEC = 47,
 175         LDNS_RR_TYPE_DNSKEY = 48,
 176         LDNS_RR_TYPE_DHCID = 49,
 177
 178         LDNS_RR_TYPE_NSEC3 = 50,
 179         LDNS_RR_TYPE_NSEC3PARAMS = 51,
 180
 181         /** draft-ietf-dnsop-trust-history */
 182         LDNS_RR_TYPE_TALINK = 58,
 183
 184         LDNS_RR_TYPE_SPF = 99,
 185
 186         LDNS_RR_TYPE_UINFO = 100,
 187         LDNS_RR_TYPE_UID = 101,
 188         LDNS_RR_TYPE_GID = 102,
 189         LDNS_RR_TYPE_UNSPEC = 103,
 190
 191         LDNS_RR_TYPE_TSIG = 250,
 192         LDNS_RR_TYPE_IXFR = 251,
 193         LDNS_RR_TYPE_AXFR = 252,
 194         /**  A request for mailbox-related records (MB, MG or MR) */
 195         LDNS_RR_TYPE_MAILB = 253,
 196         /**  A request for mail agent RRs (Obsolete - see MX) */
 197         LDNS_RR_TYPE_MAILA = 254,
 198         /**  any type (wildcard) */
 199         LDNS_RR_TYPE_ANY = 255,
 200
 201         /* RFC 4431, 5074, DNSSEC Lookaside Validation */
 202         LDNS_RR_TYPE_DLV = 32769,
 203
 204         /* type codes from nsec3 experimental phase
 205         LDNS_RR_TYPE_NSEC3 = 65324,
 206         LDNS_RR_TYPE_NSEC3PARAMS = 65325, */
 207         LDNS_RR_TYPE_FIRST = 0,
 208         LDNS_RR_TYPE_LAST  = 65535,
 209         LDNS_RR_TYPE_COUNT = LDNS_RR_TYPE_LAST - LDNS_RR_TYPE_FIRST + 1
 210 };
 211 typedef enum ldns_enum_rr_type ldns_rr_type;
 212
 213 /**
 214  * Resource Record
 215  *
 216  * This is the basic DNS element that contains actual data
 217  *
 218  * From RFC1035:
 219  * <pre>
 220 3.2.1. Format
 221
 222 All RRs have the same top level format shown below:
 223
 224                                     1  1  1  1  1  1
 225       0  1  2  3  4  5  6  7  8  9  0  1  2  3  4  5
 226     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
 227     |                                               |
 228     /                                               /
 229     /                      NAME                     /
 230     |                                               |
 231     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
 232     |                      TYPE                     |
 233     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
 234     |                     CLASS                     |
 235     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
 236     |                      TTL                      |
 237     |                                               |
 238     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
 239     |                   RDLENGTH                    |
 240     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--|
 241     /                     RDATA                     /
 242     /                                               /
 243     +--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
 244
 245 where:
 246
 247 NAME            an owner name, i.e., the name of the node to which this
 248                 resource record pertains.
 249
 250 TYPE            two octets containing one of the RR TYPE codes.
 251
 252 CLASS           two octets containing one of the RR CLASS codes.
 253
 254 TTL             a 32 bit signed integer that specifies the time interval
 255                 that the resource record may be cached before the source
 256                 of the information should again be consulted.  Zero
 257                 values are interpreted to mean that the RR can only be
 258                 used for the transaction in progress, and should not be
 259                 cached.  For example, SOA records are always distributed
 260                 with a zero TTL to prohibit caching.  Zero values can
 261                 also be used for extremely volatile data.
 262
 263 RDLENGTH        an unsigned 16 bit integer that specifies the length in
 264                 octets of the RDATA field.
 265
 266 RDATA           a variable length string of octets that describes the
 267                 resource.  The format of this information varies
 268                 according to the TYPE and CLASS of the resource record.
 269  * </pre>
 270  *
 271  * The actual amount and type of rdata fields depend on the RR type of the
 272  * RR, and can be found by using \ref ldns_rr_descriptor functions.
 273  */
 274 struct ldns_struct_rr
 275 {
 276         /**  Owner name, uncompressed */
 277         ldns_rdf        *_owner;
 278         /**  Time to live  */
 279         uint32_t        _ttl;
 280         /**  Number of data fields */
 281         size_t          _rd_count;
 282         /**  the type of the RR. A, MX etc. */
 283         ldns_rr_type    _rr_type;
 284         /**  Class of the resource record.  */
 285         ldns_rr_class   _rr_class;
 286         /* everything in the rdata is in network order */
 287         /**  The array of rdata's */
 288         ldns_rdf         **_rdata_fields;
 289         /**  question rr [it would be nicer if thous is after _rd_count]
 290                  ABI change: Fix this in next major release
 291          */
 292         bool            _rr_question;
 293 };
 294 typedef struct ldns_struct_rr ldns_rr;
 295
 296 /**
 297  * List or Set of Resource Records
 298  *
 299  * Contains a list of rr's <br>
 300  * No official RFC-like checks are made
 301  */
 302 struct ldns_struct_rr_list
 303 {
 304         size_t _rr_count;
 305         size_t _rr_capacity;
 306         ldns_rr **_rrs;
 307 };
 308 typedef struct ldns_struct_rr_list ldns_rr_list;
 309
 310 /**
 311  * Contains all information about resource record types.
 312  *
 313  * This structure contains, for all rr types, the rdata fields that are defined.
 314  */
 315 struct ldns_struct_rr_descriptor
 316 {
 317         /** Type of the RR that is described here */
 318         ldns_rr_type    _type;
 319         /** Textual name of the RR type.  */
 320         const char *_name;
 321         /** Minimum number of rdata fields in the RRs of this type.  */
 322         uint8_t     _minimum;
 323         /** Maximum number of rdata fields in the RRs of this type.  */
 324         uint8_t     _maximum;
 325         /** Wireformat specification for the rr, i.e. the types of rdata fields in their respective order. */
 326         const ldns_rdf_type *_wireformat;
 327         /** Special rdf types */
 328         ldns_rdf_type _variable;
 329         /** Specifies whether compression can be used for dnames in this RR type. */
 330         ldns_rr_compress _compress;
 331         /** The number of DNAMEs in the _wireformat string, for parsing. */
 332         uint8_t _dname_count;
 333 };
 334 typedef struct ldns_struct_rr_descriptor ldns_rr_descriptor;
 335
 336 /**
 337  * creates a new rr structure.
 338  * \return ldns_rr *
 339  */
 340 ldns_rr* ldns_rr_new(void);
 341
 342 /**
 343  * creates a new rr structure, based on the given type.
 344  * alloc enough space to hold all the rdf's
 345  */
 346 ldns_rr* ldns_rr_new_frm_type(ldns_rr_type t);
 347
 348 /**
 349  * frees an RR structure
 350  * \param[in] *rr the RR to be freed
 351  * \return void
 352  */
 353 void ldns_rr_free(ldns_rr *rr);
 354
 355 /**
 356  * creates an rr from a string.
 357  * The string should be a fully filled-in rr, like
 358  * ownername &lt;space&gt; TTL &lt;space&gt; CLASS &lt;space&gt;
 359  * TYPE &lt;space&gt; RDATA.
 360  * \param[out] n the rr to return
 361  * \param[in] str the string to convert
 362  * \param[in] default_ttl default ttl value for the rr.
 363  *            If 0 DEF_TTL will be used
 364  * \param[in] origin when the owner is relative add this.
 365  *      The caller must ldns_rdf_deep_free it.
 366  * \param[out] prev the previous ownername. if this value is not NULL,
 367  * the function overwrites this with the ownername found in this
 368  * string. The caller must then ldns_rdf_deep_free it.
 369  * \return a status msg describing an error or LDNS_STATUS_OK
 370  */
 371 ldns_status ldns_rr_new_frm_str(ldns_rr **n, const char *str,
 372                                 uint32_t default_ttl, ldns_rdf *origin,
 373                                 ldns_rdf **prev);
 374
 375 /**
 376  * creates an rr for the question section from a string, i.e.
 377  * without RDATA fields
 378  * Origin and previous RR functionality are the same as in
 379  * ldns_rr_new_frm_str()
 380  * \param[out] n the rr to return
 381  * \param[in] str the string to convert
 382  * \param[in] origin when the owner is relative add this.
 383  *      The caller must ldns_rdf_deep_free it.
 384  * \param prev the previous ownername. the function overwrite this with
 385  * the current found ownername. The caller must ldns_rdf_deep_free it.
 386  * \return a status msg describing an error or LDNS_STATUS_OK
 387  */
 388 ldns_status ldns_rr_new_question_frm_str(ldns_rr **n, const char *str,
 389                                 ldns_rdf *origin, ldns_rdf **prev);
 390
 391 /**
 392  * creates a new rr from a file containing a string.
 393  * \param[out] rr the new rr
 394  * \param[in] fp the file pointer to use
 395  * \param[in] default_ttl pointer to a default ttl for the rr. If NULL DEF_TTL will be used
 396  *            the pointer will be updated if the file contains a $TTL directive
 397  * \param[in] origin when the owner is relative add this
 398  *            the pointer will be updated if the file contains a $ORIGIN directive
 399  *            The caller must ldns_rdf_deep_free it.
 400  * \param[in] prev when the owner is whitespaces use this as the * ownername
 401  *            the pointer will be updated after the call
 402  *            The caller must ldns_rdf_deep_free it.
 403  * \return a ldns_status with an error or LDNS_STATUS_OK
 404  */
 405 ldns_status ldns_rr_new_frm_fp(ldns_rr **rr, FILE *fp, uint32_t *default_ttl, ldns_rdf **origin, ldns_rdf **prev);
 406
 407 /**
 408  * creates a new rr from a file containing a string.
 409  * \param[out] rr the new rr
 410  * \param[in] fp the file pointer to use
 411  * \param[in] default_ttl a default ttl for the rr. If NULL DEF_TTL will be used
 412  *            the pointer will be updated if the file contains a $TTL directive
 413  * \param[in] origin when the owner is relative add this
 414  *            the pointer will be updated if the file contains a $ORIGIN directive
 415  *            The caller must ldns_rdf_deep_free it.
 416  * \param[in] line_nr pointer to an integer containing the current line number (for debugging purposes)
 417  * \param[in] prev when the owner is whitespaces use this as the * ownername
 418  *            the pointer will be updated after the call
 419  *            The caller must ldns_rdf_deep_free it.
 420  * \return a ldns_status with an error or LDNS_STATUS_OK
 421  */
 422 ldns_status ldns_rr_new_frm_fp_l(ldns_rr **rr, FILE *fp, uint32_t *default_ttl, ldns_rdf **origin, ldns_rdf **prev, int *line_nr);
 423
 424 /**
 425  * sets the owner in the rr structure.
 426  * \param[in] *rr rr to operate on
 427  * \param[in] *owner set to this owner
 428  * \return void
 429  */
 430 void ldns_rr_set_owner(ldns_rr *rr, ldns_rdf *owner);
 431
 432 /**
 433  * sets the question flag in the rr structure.
 434  * \param[in] *rr rr to operate on
 435  * \param[in] question question flag
 436  * \return void
 437  */
 438 void ldns_rr_set_question(ldns_rr *rr, bool question);
 439
 440 /**
 441  * sets the ttl in the rr structure.
 442  * \param[in] *rr rr to operate on
 443  * \param[in] ttl set to this ttl
 444  * \return void
 445  */
 446 void ldns_rr_set_ttl(ldns_rr *rr, uint32_t ttl);
 447
 448 /**
 449  * sets the rd_count in the rr.
 450  * \param[in] *rr rr to operate on
 451  * \param[in] count set to this count
 452  * \return void
 453  */
 454 void ldns_rr_set_rd_count(ldns_rr *rr, size_t count);
 455
 456 /**
 457  * sets the type in the rr.
 458  * \param[in] *rr rr to operate on
 459  * \param[in] rr_type set to this type
 460  * \return void
 461  */
 462 void ldns_rr_set_type(ldns_rr *rr, ldns_rr_type rr_type);
 463
 464 /**
 465  * sets the class in the rr.
 466  * \param[in] *rr rr to operate on
 467  * \param[in] rr_class set to this class
 468  * \return void
 469  */
 470 void ldns_rr_set_class(ldns_rr *rr, ldns_rr_class rr_class);
 471
 472 /**
 473  * sets a rdf member, it will be set on the
 474  * position given. The old value is returned, like pop.
 475  * \param[in] *rr the rr to operate on
 476  * \param[in] *f the rdf to set
 477  * \param[in] position the position the set the rdf
 478  * \return  the old value in the rr, NULL on failyre
 479  */
 480 ldns_rdf* ldns_rr_set_rdf(ldns_rr *rr, const ldns_rdf *f, size_t position);
 481
 482 /**
 483  * sets rd_field member, it will be
 484  * placed in the next available spot.
 485  * \param[in] *rr rr to operate on
 486  * \param[in] *f the data field member to set
 487  * \return bool
 488  */
 489 bool ldns_rr_push_rdf(ldns_rr *rr, const ldns_rdf *f);
 490
 491 /**
 492  * removes a rd_field member, it will be
 493  * popped from the last position.
 494  * \param[in] *rr rr to operate on
 495  * \return rdf which was popped (null if nothing)
 496  */
 497 ldns_rdf* ldns_rr_pop_rdf(ldns_rr *rr);
 498
 499 /**
 500  * returns the rdata field member counter.
 501  * \param[in] *rr rr to operate on
 502  * \param[in] nr the number of the rdf to return
 503  * \return ldns_rdf *
 504  */
 505 ldns_rdf* ldns_rr_rdf(const ldns_rr *rr, size_t nr);
 506
 507 /**
 508  * returns the owner name of an rr structure.
 509  * \param[in] *rr rr to operate on
 510  * \return ldns_rdf *
 511  */
 512 ldns_rdf* ldns_rr_owner(const ldns_rr *rr);
 513
 514 /**
 515  * returns the question flag of an rr structure.
 516  * \param[in] *rr rr to operate on
 517  * \return bool true if question
 518  */
 519 bool ldns_rr_is_question(const ldns_rr *rr);
 520
 521 /**
 522  * returns the ttl of an rr structure.
 523  * \param[in] *rr the rr to read from
 524  * \return the ttl of the rr
 525  */
 526 uint32_t ldns_rr_ttl(const ldns_rr *rr);
 527
 528 /**
 529  * returns the rd_count of an rr structure.
 530  * \param[in] *rr the rr to read from
 531  * \return the rd count of the rr
 532  */
 533 size_t ldns_rr_rd_count(const ldns_rr *rr);
 534
 535 /**
 536  * returns the type of the rr.
 537  * \param[in] *rr the rr to read from
 538  * \return the type of the rr
 539  */
 540 ldns_rr_type ldns_rr_get_type(const ldns_rr *rr);
 541
 542 /**
 543  * returns the class of the rr.
 544  * \param[in] *rr the rr to read from
 545  * \return the class of the rr
 546  */
 547 ldns_rr_class ldns_rr_get_class(const ldns_rr *rr);
 548
 549 /* rr_lists */
 550
 551 /**
 552  * returns the number of rr's in an rr_list.
 553  * \param[in] rr_list  the rr_list to read from
 554  * \return the number of rr's
 555  */
 556 size_t ldns_rr_list_rr_count(const ldns_rr_list *rr_list);
 557
 558 /**
 559  * sets the number of rr's in an rr_list.
 560  * \param[in] rr_list the rr_list to set the count on
 561  * \param[in] count the number of rr in this list
 562  * \return void
 563  */
 564 void ldns_rr_list_set_rr_count(ldns_rr_list *rr_list, size_t count);
 565
 566 /**
 567  * set a rr on a specific index in a ldns_rr_list
 568  * \param[in] rr_list the rr_list to use
 569  * \param[in] r the rr to set
 570  * \param[in] count index into the rr_list
 571  * \return the old rr which was stored in the rr_list, or
 572  * NULL is the index was too large
 573  * set a specific rr */
 574 ldns_rr * ldns_rr_list_set_rr(ldns_rr_list *rr_list, const ldns_rr *r, size_t count);
 575
 576 /**
 577  * returns a specific rr of an rrlist.
 578  * \param[in] rr_list the rr_list to read from
 579  * \param[in] nr return this rr
 580  * \return the rr at position nr
 581  */
 582 ldns_rr* ldns_rr_list_rr(const ldns_rr_list *rr_list, size_t nr);
 583
 584 /**
 585  * creates a new rr_list structure.
 586  * \return a new rr_list structure
 587  */
 588 ldns_rr_list* ldns_rr_list_new();
 589
 590 /**
 591  * frees an rr_list structure.
 592  * \param[in] rr_list the list to free
 593  */
 594 void ldns_rr_list_free(ldns_rr_list *rr_list);
 595
 596 /**
 597  * frees an rr_list structure and all rrs contained therein.
 598  * \param[in] rr_list the list to free
 599  */
 600 void ldns_rr_list_deep_free(ldns_rr_list *rr_list);
 601
 602 /**
 603  * concatenates two ldns_rr_lists together. This modifies
 604  * *left (to extend it and add the pointers from *right).
 605  * \param[in] left the leftside
 606  * \param[in] right the rightside
 607  * \return a left with right concatenated to it
 608  */
 609 bool ldns_rr_list_cat(ldns_rr_list *left, ldns_rr_list *right);
 610
 611 /**
 612  * concatenates two ldns_rr_lists together, but makes clones of the rr's
 613  * (instead of pointer copying).
 614  * \param[in] left the leftside
 615  * \param[in] right the rightside
 616  * \return a new rr_list with leftside/rightside concatenated
 617  */
 618 ldns_rr_list* ldns_rr_list_cat_clone(ldns_rr_list *left, ldns_rr_list *right);
 619
 620 /**
 621  * pushes an rr to an rrlist.
 622  * \param[in] rr_list the rr_list to push to
 623  * \param[in] rr the rr to push
 624  * \return false on error, otherwise true
 625  */
 626 bool ldns_rr_list_push_rr(ldns_rr_list *rr_list, const ldns_rr *rr);
 627
 628 /**
 629  * pushes an rr_list to an rrlist.
 630  * \param[in] rr_list the rr_list to push to
 631  * \param[in] push_list the rr_list to push
 632  * \return false on error, otherwise true
 633  */
 634 bool ldns_rr_list_push_rr_list(ldns_rr_list *rr_list, const ldns_rr_list *push_list);
 635
 636 /**
 637  * pops the last rr from an rrlist.
 638  * \param[in] rr_list the rr_list to pop from
 639  * \return NULL if nothing to pop. Otherwise the popped RR
 640  */
 641 ldns_rr* ldns_rr_list_pop_rr(ldns_rr_list *rr_list);
 642
 643 /**
 644  * pops an  rr_list of size s from an rrlist.
 645  * \param[in] rr_list the rr_list to pop from
 646  * \param[in] size the number of rr's to pop
 647  * \return NULL if nothing to pop. Otherwise the popped rr_list
 648  */
 649 ldns_rr_list* ldns_rr_list_pop_rr_list(ldns_rr_list *rr_list, size_t size);
 650
 651 /**
 652  * returns true if the given rr is one of the rrs in the
 653  * list, or if it is equal to one
 654  * \param[in] rr_list the rr_list to check
 655  * \param[in] rr the rr to check
 656  * \return true if rr_list contains rr, false otherwise
 657  */
 658 bool ldns_rr_list_contains_rr(const ldns_rr_list *rr_list, ldns_rr *rr);
 659
 660 /**
 661  * checks if an rr_list is a rrset.
 662  * \param[in] rr_list the rr_list to check
 663  * \return true if it is an rrset otherwise false
 664  */
 665 bool ldns_is_rrset(ldns_rr_list *rr_list);
 666
 667 /**
 668  * pushes an rr to an rrset (which really are rr_list's).
 669  * \param[in] *rr_list the rrset to push the rr to
 670  * \param[in] *rr the rr to push
 671  * \return true if the push succeeded otherwise false
 672  */
 673 bool ldns_rr_set_push_rr(ldns_rr_list *rr_list, ldns_rr *rr);
 674
 675 /**
 676  * pops the last rr from an rrset. This function is there only
 677  * for the symmetry.
 678  * \param[in] rr_list the rr_list to pop from
 679  * \return NULL if nothing to pop. Otherwise the popped RR
 680  *
 681  */
 682 ldns_rr* ldns_rr_set_pop_rr(ldns_rr_list *rr_list);
 683
 684 /**
 685  * pops the first rrset from the list,
 686  * the list must be sorted, so that all rr's from each rrset
 687  * are next to each other
 688  */
 689 ldns_rr_list *ldns_rr_list_pop_rrset(ldns_rr_list *rr_list);
 690
 691
 692 /**
 693  * retrieves a rrtype by looking up its name.
 694  * \param[in] name a string with the name
 695  * \return the type which corresponds with the name
 696  */
 697 ldns_rr_type ldns_get_rr_type_by_name(const char *name);
 698
 699 /**
 700  * retrieves a class by looking up its name.
 701  * \param[in] name string with the name
 702  * \return the cass which corresponds with the name
 703  */
 704 ldns_rr_class ldns_get_rr_class_by_name(const char *name);
 705
 706 /**
 707  * clones a rr and all its data
 708  * \param[in] rr the rr to clone
 709  * \return the new rr or NULL on failure
 710  */
 711 ldns_rr* ldns_rr_clone(const ldns_rr *rr);
 712
 713 /**
 714  * clones an rrlist.
 715  * \param[in] rrlist the rrlist to clone
 716  * \return the cloned rr list
 717  */
 718 ldns_rr_list* ldns_rr_list_clone(const ldns_rr_list *rrlist);
 719
 720 /**
 721  * sorts an rr_list (canonical wire format). the sorting is done inband.
 722  * \param[in] unsorted the rr_list to be sorted
 723  * \return void
 724  */
 725 void ldns_rr_list_sort(ldns_rr_list *unsorted);
 726
 727 /**
 728  * compares two rrs. The TTL is not looked at.
 729  * \param[in] rr1 the first one
 730  * \param[in] rr2 the second one
 731  * \return 0 if equal
 732  *         -1 if rr1 comes before rr2
 733  *         +1 if rr2 comes before rr1
 734  */
 735 int ldns_rr_compare(const ldns_rr *rr1, const ldns_rr *rr2);
 736
 737 /**
 738  * compares two rrs, up to the rdata.
 739  * \param[in] rr1 the first one
 740  * \param[in] rr2 the second one
 741  * \return 0 if equal
 742  *         -1 if rr1 comes before rr2
 743  *         +1 if rr2 comes before rr1
 744  */
 745 int ldns_rr_compare_no_rdata(const ldns_rr *rr1, const ldns_rr *rr2);
 746
 747 /**
 748  * compares the wireformat of two rrs, contained in the given buffers.
 749  * \param[in] rr1_buf the first one
 750  * \param[in] rr2_buf the second one
 751  * \return 0 if equal
 752  *         -1 if rr1_buf comes before rr2_buf
 753  *         +1 if rr2_buf comes before rr1_buf
 754  */
 755 int ldns_rr_compare_wire(ldns_buffer *rr1_buf, ldns_buffer *rr2_buf);
 756
 757 /**
 758  * returns true of the given rr's are equal.
 759  * Also returns true if one record is a DS that represents the
 760  * same DNSKEY record as the other record
 761  * \param[in] rr1 the first rr
 762  * \param[in] rr2 the second rr
 763  * \return true if equal otherwise false
 764  */
 765 bool ldns_rr_compare_ds(const ldns_rr *rr1, const ldns_rr *rr2);
 766
 767 /**
 768  * compares two rr listss.
 769  * \param[in] rrl1 the first one
 770  * \param[in] rrl2 the second one
 771  * \return 0 if equal
 772  *         -1 if rrl1 comes before rrl2
 773  *         +1 if rrl2 comes before rrl1
 774  */
 775 int ldns_rr_list_compare(const ldns_rr_list *rrl1, const ldns_rr_list *rrl2);
 776
 777 /**
 778  * calculates the uncompressed size of an RR.
 779  * \param[in] r the rr to operate on
 780  * \return size of the rr
 781  */
 782 size_t ldns_rr_uncompressed_size(const ldns_rr *r);
 783
 784 /**
 785  * converts each dname in a rr to its canonical form.
 786  * \param[in] rr the rr to work on
 787  * \return void
 788  */
 789 void ldns_rr2canonical(ldns_rr *rr);
 790
 791 /**
 792  * converts each dname in each rr in a rr_list to its canonical form.
 793  * \param[in] rr_list the rr_list to work on
 794  * \return void
 795  */
 796 void ldns_rr_list2canonical(ldns_rr_list *rr_list);
 797
 798 /**
 799  * counts the number of labels of the ownername.
 800  * \param[in] rr count the labels of this rr
 801  * \return the number of labels
 802  */
 803 uint8_t ldns_rr_label_count(ldns_rr *rr);
 804
 805 /**
 806  * returns the resource record descriptor for the given rr type.
 807  *
 808  * \param[in] type the type value of the rr type
 809  *\return the ldns_rr_descriptor for this type
 810  */
 811 const ldns_rr_descriptor *ldns_rr_descript(uint16_t type);
 812
 813 /**
 814  * returns the minimum number of rdata fields of the rr type this descriptor describes.
 815  *
 816  * \param[in]  descriptor for an rr type
 817  * \return the minimum number of rdata fields
 818  */
 819 size_t ldns_rr_descriptor_minimum(const ldns_rr_descriptor *descriptor);
 820
 821 /**
 822  * returns the maximum number of rdata fields of the rr type this descriptor describes.
 823  *
 824  * \param[in]  descriptor for an rr type
 825  * \return the maximum number of rdata fields
 826  */
 827 size_t ldns_rr_descriptor_maximum(const ldns_rr_descriptor *descriptor);
 828
 829 /**
 830  * returns the rdf type for the given rdata field number of the rr type for the given descriptor.
 831  *
 832  * \param[in] descriptor for an rr type
 833  * \param[in] field the field number
 834  * \return the rdf type for the field
 835  */
 836 ldns_rdf_type ldns_rr_descriptor_field_type(const ldns_rr_descriptor *descriptor, size_t field);
 837
 838 /**
 839  * Return the rr_list which matches the rdf at position field. Think
 840  * type-covered stuff for RRSIG
 841  *
 842  * \param[in] l the rr_list to look in
 843  * \param[in] r the rdf to use for the comparison
 844  * \param[in] pos at which position can we find the rdf
 845  *
 846  * \return a new rr list with only the RRs that match
 847  *
 848  */
 849 ldns_rr_list *ldns_rr_list_subtype_by_rdf(ldns_rr_list *l, ldns_rdf *r, size_t pos);
 850
 851 /**
 852  * convert an rdf of type LDNS_RDF_TYPE_TYPE to an actual
 853  * LDNS_RR_TYPE. This is usefull in the case when inspecting
 854  * the rrtype covered field of an RRSIG.
 855  * \param[in] rd the rdf to look at
 856  * \return a ldns_rr_type with equivalent LDNS_RR_TYPE
 857  *
 858  */
 859 ldns_rr_type    ldns_rdf2rr_type(const ldns_rdf *rd);
 860
 861 /**
 862  * Returns the type of the first element of the RR
 863  * If there are no elements present, 0 is returned
 864  *
 865  * \param[in] rr_list The rr list
 866  * \return rr_type of the first element, or 0 if the list is empty
 867  */
 868 ldns_rr_type
 869 ldns_rr_list_type(const ldns_rr_list *rr_list);
 870
 871 /**
 872  * Returns the owner domain name rdf of the first element of the RR
 873  * If there are no elements present, NULL is returned
 874  *
 875  * \param[in] rr_list The rr list
 876  * \return dname of the first element, or NULL if the list is empty
 877  */
 878 ldns_rdf *
 879 ldns_rr_list_owner(const ldns_rr_list *rr_list);
 880
 881 #ifdef __cplusplus
 882 }
 883 #endif
 884
 885 #endif /* LDNS_RR_H */