]> git.meshlink.io Git - catta/blob - avahi-common/defs.h
* format unknown DNS records according to RFC3597
[catta] / avahi-common / defs.h
1 #ifndef foodefshfoo
2 #define foodefshfoo
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 /** \file defs.h Some common definitions */
26
27 #include <avahi-common/cdecl.h>
28
29 /** \mainpage
30  *  
31  * \section choose_api Choosing an API
32  *
33  * Avahi provides three programming APIs for integration of
34  * mDNS/DNS-SD features into your progams:
35  *
36  * \li avahi-core: an API for embedding a complete mDNS/DNS-SD stack
37  * into your software. This is intended for developers of embedded
38  * ampliances only. We dissuade from using this API in normal desktop
39  * applications since it is not a good idea to run multiple mDNS
40  * stacks simultaneously on the same host.
41  * \li The DBUS API: an extensive DBUS interface for browsing and
42  * registering mDNS/DNS-SD services using avahi-daemon. We recommend
43  * to use this API for software written in any language but
44  * C. (i.e. python)
45  * \li avahi-client: a simplifying C wrapper around the DBUS API. We
46  * recommend to use this API in C or C++ progams. The DBUS internals
47  * are hidden completely.
48  * 
49  * All three APIs are very similar, however avahi-core is the most powerful.
50  *
51  * In addition to the three APIs described above Avahi supports two
52  * compatibility libraries:
53  *
54  * \li avahi-compat-libdns_sd: the original Bonjour API as documented
55  * in the header file "dns_sd.h" by Apple Computer, Inc.
56  *
57  * \li avahi-compat-howl: the HOWL API as released with HOWL 0.9.8 by
58  * Porchdog Software.
59  *
60  * Please note that these compatibility layers are incomplete and
61  * generally a waste of resources. We strongly encourage everyone to
62  * use our native APIs for newly written programs and to port older
63  * programs to one of them!
64  * 
65  * \section error_reporting Error Reporting
66  *
67  * Some notes on the Avahi error handling:
68  *
69  * - Error codes are negative integers and defined as AVAHI_ERR_xx
70  * - If a function returns some kind of non-negative integer value
71  * on success, a failure is indicated by returning the error code
72  * directly.
73  * - If a function returns a pointer of some kind on success, a
74  * failure is indicated by returning NULL
75  * - The last error number may be retrieved by calling
76  * avahi_server_errno() (for the server API) or avahi_client_errno()
77  * (for the client API)
78  * - Just like the libc errno variable the Avahi errno is NOT reset
79  * to AVAHI_OK if a function call succeeds.
80  * - You may convert a numeric error code into a human readable
81  * string using avahi_strerror()
82  * - The constructor functions avahi_server_new() and
83  * avahi_client_new() return the error code in a call-by-reference
84  * argument
85  *
86  * \section event_loop Event Loop Abstraction
87  *
88  * Avahi uses for both avahi-client and avahi-core a simple event loop
89  * abstraction layer.A table AvahiPoll which contains function
90  * pointers for user defined timeout and I/O condition event source
91  * implementations, needs to be passed to avahi_server_new() and
92  * avahi_client_new(). An adapter for this abstraction layer is
93  * available for the GLib main loop in the object AvahiGLibPoll. A
94  * simple stand-alone implementation is available under the name
95  * AvahiSimplePoll.
96  *
97  * \section good_publish How to Register Services
98  *
99  * - Subscribe to server state changes. Pass a callback function
100  * pointer to avahi_client_new()/avahi_server_new(). It will be called
101  * whenever the server state changes.
102  * - Only register your services when the server is in state
103  * AVAHI_SERVER_RUNNING. If you register your services in other server
104  * states they might not be accessible since the local host name is
105  * not established.
106  * - Remove your services when the server enters
107  * AVAHI_SERVER_COLLISION state. Your services may no be reachable
108  * anymore since the local host name is no longer established.
109  * - When registering services, use the following algorithm:
110  *   - Create a new entry group (i.e. avahi_entry_group_new())
111  *   - Add your service(s)/additional host names (i.e. avahi_entry_group_add_service())
112  *   - Commit the entry group (i.e. avahi_entry_group_commit())
113  * - Subscribe to entry group state changes.
114  * - If the entry group enters AVAHI_ENTRY_GROUP_COLLISION state the
115  * services of the entry group are automatically removed from the
116  * server. You may immediately add your services back to the entry
117  * group (but with new names, perhaps using
118  * avahi_alternative_service_name()) and commit again. Please do not
119  * free the entry group and create a new one. This would inhibit some
120  * traffic limiting algorithms in mDNS.
121  * - When you need to modify your services, use the AVAHI_PUBLISH_UPDATE flag. Please do not
122  * free the entry group and create a new one. This would inhibit some
123  * traffic limiting algorithms in mDNS.
124  *
125  * The linked functions belong to avahi-client. They all have counterparts in the DBUS API and avahi-core.
126  *
127  * \section good_browse How to Browse for Services
128  *
129  * - For normal applications you need to call avahi_service_browser_new()
130  * for the service type you want to browse for. Use
131  * avahi_client_resolve_service() to acquire service data for a a service
132  * name.
133  * - You can use avahi_domain_browser_new() to get a list of announced
134  * browsing domains. Please note that not all domains whith services
135  * on the LAN are mandatorily announced.
136  * - Network monitor software may use avahi_service_type_browser_new()
137  * to browse for the list of available service types on the LAN. This
138  * API should NOT be used in normal software since it increases
139  * traffic heavily.
140  * - There is no need to subscribe to server state changes.
141  *  
142  * The linked functions belong to avahi-client. They all have counterparts in the DBUS API and avahi-core.
143  *  
144  */
145
146 AVAHI_C_DECL_BEGIN
147
148 /** States of an entry group object */
149 typedef enum {
150     AVAHI_ENTRY_GROUP_UNCOMMITED,    /**< The group has not yet been commited, the user must still call avahi_entry_group_commit() */
151     AVAHI_ENTRY_GROUP_REGISTERING,   /**< The entries of the group are currently being registered */
152     AVAHI_ENTRY_GROUP_ESTABLISHED,   /**< The entries have successfully been established */
153     AVAHI_ENTRY_GROUP_COLLISION,     /**< A name collision for one of the entries in the group has been detected, the entries have been withdrawn */
154     AVAHI_ENTRY_GROUP_FAILURE        /**< Some kind of failure happened, the entries have been withdrawn */
155 } AvahiEntryGroupState;
156
157 /** The type of domain to browse for */
158 typedef enum {
159     AVAHI_DOMAIN_BROWSER_REGISTER,          /**< Browse for a list of available registering domains */
160     AVAHI_DOMAIN_BROWSER_REGISTER_DEFAULT,  /**< Browse for the default registering domain */
161     AVAHI_DOMAIN_BROWSER_BROWSE,            /**< Browse for a list of available browsing domains */
162     AVAHI_DOMAIN_BROWSER_BROWSE_DEFAULT,    /**< Browse for the default browsing domain */
163     AVAHI_DOMAIN_BROWSER_BROWSE_LEGACY,     /**< Legacy browse domain - see DNS-SD spec for more information */
164     AVAHI_DOMAIN_BROWSER_MAX
165 } AvahiDomainBrowserType;
166
167 /** Some flags for publishing functions */
168 typedef enum {
169     AVAHI_PUBLISH_UNIQUE = 1,           /**< For raw records: The RRset is intended to be unique */
170     AVAHI_PUBLISH_NO_PROBE = 2,         /**< For raw records: Though the RRset is intended to be unique no probes shall be sent */
171     AVAHI_PUBLISH_NO_ANNOUNCE = 4,      /**< For raw records: Do not announce this RR to other hosts */
172     AVAHI_PUBLISH_ALLOW_MULTIPLE = 8,   /**< For raw records: Allow multiple local records of this type, even if they are intended to be unique */
173     AVAHI_PUBLISH_NO_REVERSE = 16,      /**< For address records: don't create a reverse (PTR) entry */
174     AVAHI_PUBLISH_NO_COOKIE = 32,       /**< For service records: do not implicitly add the local service cookie to TXT data */
175     AVAHI_PUBLISH_UPDATE = 64           /**< Update existing records instead of adding new ones */
176 } AvahiPublishFlags;
177
178 /** Some flags for lookup functions */
179 typedef enum {
180     AVAHI_LOOKUP_USE_WIDE_AREA = 1,    /**< Force lookup via wide area DNS */
181     AVAHI_LOOKUP_USE_MULTICAST = 2,    /**< Force lookup via multicast DNS */
182     AVAHI_LOOKUP_NO_TXT = 4,           /**< When doing service resolving, don't lookup TXT record */
183     AVAHI_LOOKUP_NO_ADDRESS = 8        /**< When doing service resolving, don't lookup A/AAAA record */
184 } AvahiLookupFlags;
185
186 /** Some flags for lookup callback functions */
187 typedef enum {
188     AVAHI_LOOKUP_RESULT_CACHED = 1,         /**< This response originates from the cache */
189     AVAHI_LOOKUP_RESULT_WIDE_AREA = 2,      /**< This response originates from wide area DNS */
190     AVAHI_LOOKUP_RESULT_MULTICAST = 4,      /**< This response originates from multicast DNS */
191     AVAHI_LOOKUP_RESULT_LOCAL = 8,          /**< This record/service resides on and was announced by the local host. Only available in service and record browsers and only on AVAHI_BROWSER_NEW. */
192     AVAHI_LOOKUP_RESULT_OUR_OWN = 16        /**< This service belongs to the same local client as the browser object. Only available in avahi-client, and only for service browsers and only on AVAHI_BROWSER_NEW. */
193 } AvahiLookupResultFlags;
194
195 /** Type of callback event when browsing */
196 typedef enum {
197     AVAHI_BROWSER_NEW,               /**< The object is new on the network */
198     AVAHI_BROWSER_REMOVE,            /**< The object has been removed from the network */
199     AVAHI_BROWSER_CACHE_EXHAUSTED,   /**< One-time event, to notify the user that all entries from the caches have been send */
200     AVAHI_BROWSER_ALL_FOR_NOW,       /**< One-time event, to notify the user that more records will probably not show up in the near future, i.e. all cache entries have been read and all static servers been queried */
201     AVAHI_BROWSER_FAILURE            /**< Browsing failed due to some reason which can be retrieved using avahi_server_errno()/avahi_client_errno() */
202 } AvahiBrowserEvent;
203
204 /** Type of callback event when resolving */
205 typedef enum {
206     AVAHI_RESOLVER_FOUND,          /**< RR found, resolving successful */
207     AVAHI_RESOLVER_FAILURE         /**< Resolving failed due to some reason which can be retrieved using avahi_server_errno()/avahi_client_errno() */
208 } AvahiResolverEvent;
209
210 /** States of a server object */
211 typedef enum {
212     AVAHI_SERVER_INVALID,          /**< Invalid state (initial) */ 
213     AVAHI_SERVER_REGISTERING,      /**< Host RRs are being registered */
214     AVAHI_SERVER_RUNNING,          /**< All host RRs have been established */
215     AVAHI_SERVER_COLLISION,        /**< There is a collision with a host RR. All host RRs have been withdrawn, the user should set a new host name via avahi_server_set_host_name() */
216     AVAHI_SERVER_FAILURE           /**< Some fatal failure happened, the server is unable to proceed */
217 } AvahiServerState;
218
219 /** For every service a special TXT item is implicitly added, which
220  * contains a random cookie which is private to the local daemon. This
221  * can be used by clients to determine if two services on two
222  * different subnets are effectively the same. */
223 #define AVAHI_SERVICE_COOKIE "org.freedesktop.Avahi.cookie"
224
225 /** In invalid cookie as special value */
226 #define AVAHI_SERVICE_COOKIE_INVALID (0)
227
228 /** DNS record types, see RFC 1035 */
229 enum {
230     AVAHI_DNS_TYPE_A = 0x01,
231     AVAHI_DNS_TYPE_NS = 0x02,
232     AVAHI_DNS_TYPE_CNAME = 0x05,
233     AVAHI_DNS_TYPE_SOA = 0x06,
234     AVAHI_DNS_TYPE_PTR = 0x0C,
235     AVAHI_DNS_TYPE_HINFO = 0x0D,
236     AVAHI_DNS_TYPE_MX = 0x0F,
237     AVAHI_DNS_TYPE_TXT = 0x10,
238     AVAHI_DNS_TYPE_AAAA = 0x1C,
239     AVAHI_DNS_TYPE_SRV = 0x21,
240 };
241
242 /** DNS record classes, see RFC 1035 */
243 enum {
244     AVAHI_DNS_CLASS_IN = 0x01,          /**< Probably the only class we will ever use */
245 };
246
247 /** The default TTL for RRs which contain a host name of some kind. */
248 #define AVAHI_DEFAULT_TTL_HOST_NAME (120)
249
250 /** The default TTL for all other records. */
251 #define AVAHI_DEFAULT_TTL (75*60)
252
253 AVAHI_C_DECL_END
254
255 #endif