]> git.meshlink.io Git - catta/blob - avahi-common/rr.h
improve documentation
[catta] / avahi-common / rr.h
1 #ifndef foorrhfoo
2 #define foorrhfoo
3
4 /* $Id$ */
5
6 /***
7   This file is part of avahi.
8  
9   avahi is free software; you can redistribute it and/or modify it
10   under the terms of the GNU Lesser General Public License as
11   published by the Free Software Foundation; either version 2.1 of the
12   License, or (at your option) any later version.
13  
14   avahi is distributed in the hope that it will be useful, but WITHOUT
15   ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
16   or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General
17   Public License for more details.
18  
19   You should have received a copy of the GNU Lesser General Public
20   License along with avahi; if not, write to the Free Software
21   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
22   USA.
23 ***/
24
25 #include <glib.h>
26
27 #include <avahi-common/strlst.h>
28 #include <avahi-common/address.h>
29 #include <avahi-common/cdecl.h>
30
31 /** \file rr.h Functions and definitions for manipulating DNS resource record (RR) data. */
32
33 AVAHI_C_DECL_BEGIN
34
35 /** DNS record types, see RFC 1035 */
36 enum {
37     AVAHI_DNS_TYPE_A = 0x01,
38     AVAHI_DNS_TYPE_NS = 0x02,
39     AVAHI_DNS_TYPE_CNAME = 0x05,
40     AVAHI_DNS_TYPE_SOA = 0x06,
41     AVAHI_DNS_TYPE_PTR = 0x0C,
42     AVAHI_DNS_TYPE_HINFO = 0x0D,
43     AVAHI_DNS_TYPE_MX = 0x0F,
44     AVAHI_DNS_TYPE_TXT = 0x10,
45     AVAHI_DNS_TYPE_AAAA = 0x1C,
46     AVAHI_DNS_TYPE_SRV = 0x21,
47     AVAHI_DNS_TYPE_ANY = 0xFF /**< Special query type for requesting all records */
48 };
49
50 /** DNS record classes, see RFC 1035 */
51 enum {
52     AVAHI_DNS_CLASS_IN = 0x01,          /**< Probably the only class we will ever use */
53     AVAHI_DNS_CLASS_ANY = 0xFF,         /**< Special query type for requesting all records */
54     AVAHI_DNS_CACHE_FLUSH = 0x8000,     /**< Not really a class but a bit which may be set in response packets, see mDNS spec for more information */
55     AVAHI_DNS_UNICAST_RESPONSE = 0x8000 /**< Not really a class but a bit which may be set in query packets, see mDNS spec for more information */
56 };
57
58 /** The default TTL for RRs which contain a host name of some kind. */
59 #define AVAHI_DEFAULT_TTL_HOST_NAME (120)
60
61 /** The default TTL for all other records. */
62 #define AVAHI_DEFAULT_TTL (75*60)
63
64 /** Encapsulates a DNS query key consisting of class, type and
65     name. Use avahi_key_ref()/avahi_key_unref() for manipulating the
66     reference counter. The structure is intended to be treated as "immutable", no
67     changes should be imposed after creation */
68 typedef struct {
69     guint ref;         /**< Reference counter */
70     gchar *name;       /**< Record name */
71     guint16 clazz;     /**< Record class, one of the AVAHI_DNS_CLASS_xxx constants */
72     guint16 type;      /**< Record type, one of the AVAHI_DNS_TYPE_xxx constants */
73 } AvahiKey;
74
75 /** Encapsulates a DNS resource record. The structure is intended to
76  * be treated as "immutable", no changes should be imposed after
77  * creation. */
78 typedef struct  {
79     guint ref;       /**< Reference counter */
80     AvahiKey *key;   /**< Reference to the query key of thsi record */
81     
82     guint32 ttl;     /**< DNS TTL of this record */
83
84     union {
85
86         
87         struct {
88             gpointer data;
89             guint16 size;
90         } generic; /**< Generic record data for unknown types */
91
92         
93         struct {
94             guint16 priority;
95             guint16 weight;
96             guint16 port;
97             gchar *name;
98         } srv; /**< Data for SRV records */
99
100         struct {
101             gchar *name;
102         } ptr; /**< Data for PTR an CNAME records */
103
104         struct {
105             gchar *cpu;
106             gchar *os;
107         } hinfo; /**< Data for HINFO records */
108
109         struct {
110             AvahiStringList *string_list;
111         } txt; /**< Data for TXT records */
112
113         struct {
114             AvahiIPv4Address address;
115         } a; /**< Data for A records */
116
117         struct {
118             AvahiIPv6Address address;
119         } aaaa; /**< Data for AAAA records */
120
121     } data; /**< Record data */
122     
123 } AvahiRecord;
124
125 /** Create a new AvahiKey object. The reference counter will be set to 1. */
126 AvahiKey *avahi_key_new(const gchar *name, guint16 clazz, guint16 type);
127
128 /** Increase the reference counter of an AvahiKey object by one */
129 AvahiKey *avahi_key_ref(AvahiKey *k);
130
131 /** Decrease the reference counter of an AvahiKey object by one */
132 void avahi_key_unref(AvahiKey *k);
133
134 /** Check whether two AvahiKey object contain the same
135  * data. AVAHI_DNS_CLASS_ANY/AVAHI_DNS_TYPE_ANY are treated like any
136  * other class/type. */
137 gboolean avahi_key_equal(const AvahiKey *a, const AvahiKey *b); 
138
139 /** Match a key to a key pattern. The pattern has a type of
140 AVAHI_DNS_CLASS_ANY, the classes are taken to be equal. Same for the
141 type. If the pattern has neither class nor type with ANY constants,
142 this function is identical to avahi_key_equal(). In contrast to
143 avahi_equal() this function is not commutative. */
144 gboolean avahi_key_pattern_match(const AvahiKey *pattern, const AvahiKey *k);
145
146 /** Check whether a key is a pattern key, i.e. the class/type has a
147  * value of AVAHI_DNS_CLASS_ANY/AVAHI_DNS_TYPE_ANY */
148 gboolean avahi_key_is_pattern(const AvahiKey *k);
149
150 /** Return a numeric hash value for a key for usage in hash tables. */
151 guint avahi_key_hash(const AvahiKey *k);
152
153 /** Create a new record object. Record data should be filled in right after creation. The reference counter is set to 1. */
154 AvahiRecord *avahi_record_new(AvahiKey *k, guint32 ttl);
155
156 /** Create a new record object. Record data should be filled in right after creation. The reference counter is set to 1. */
157 AvahiRecord *avahi_record_new_full(const gchar *name, guint16 clazz, guint16 type, guint32 ttl);
158
159 /** Increase the reference counter of an AvahiRecord by one. */
160 AvahiRecord *avahi_record_ref(AvahiRecord *r);
161
162 /** Decrease the reference counter of an AvahiRecord by one. */
163 void avahi_record_unref(AvahiRecord *r);
164
165 /** Return a textual representation of the specified DNS class. The
166  * returned pointer points to a read only internal string. */
167 const gchar *avahi_dns_class_to_string(guint16 clazz);
168
169 /** Return a textual representation of the specified DNS class. The
170  * returned pointer points to a read only internal string. */
171 const gchar *avahi_dns_type_to_string(guint16 type);
172
173 /** Create a textual representation of the specified key. g_free() the
174  * result! */
175 gchar *avahi_key_to_string(const AvahiKey *k);
176
177 /** Create a textual representation of the specified record, similar
178  * in style to BIND zone file data. g_free() the result! */
179 gchar *avahi_record_to_string(const AvahiRecord *r); 
180
181 /** Check whether two records are equal (regardless of the TTL */
182 gboolean avahi_record_equal_no_ttl(const AvahiRecord *a, const AvahiRecord *b);
183
184 /** Make a deep copy of an AvahiRecord object */
185 AvahiRecord *avahi_record_copy(AvahiRecord *r);
186
187 /** Returns a maximum estimate for the space that is needed to store
188  * this key in a DNS packet. */
189 guint avahi_key_get_estimate_size(AvahiKey *k);
190
191 /** Returns a maximum estimate for the space that is needed to store
192  * the record in a DNS packet. */
193 guint avahi_record_get_estimate_size(AvahiRecord *r);
194
195 /** Do a mDNS spec conforming lexicographical comparison of the two
196  * records. Return a negative value if a < b, a positive if a > b,
197  * zero if equal. */
198 gint avahi_record_lexicographical_compare(AvahiRecord *a, AvahiRecord *b);
199
200 /** Return TRUE if the specified record is an mDNS goodbye record. i.e. TTL is zero. */
201 gboolean avahi_record_is_goodbye(AvahiRecord *r);
202
203 AVAHI_C_DECL_END
204
205 #endif