7 This file is part of avahi.
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.
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.
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
28 /** An mDNS responder object */
29 typedef struct AvahiServer AvahiServer;
31 /** A locally registered DNS resource record */
32 typedef struct AvahiEntry AvahiEntry;
34 /** A group of locally registered DNS RRs */
35 typedef struct AvahiEntryGroup AvahiEntryGroup;
37 #include <avahi-common/address.h>
38 #include <avahi-common/rr.h>
39 #include <avahi-common/alternative.h>
41 /** States of a server object */
43 AVAHI_SERVER_INVALID = -1, /**< Invalid state (initial) */
44 AVAHI_SERVER_REGISTERING = 0, /**< Host RRs are being registered */
45 AVAHI_SERVER_RUNNING, /**< All host RRs have been established */
46 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() */
47 AVAHI_SERVER_SLEEPING /**< The host or domain name has changed and the server waits for old entries to be expired */
50 /** Flags for server entries */
52 AVAHI_ENTRY_NULL = 0, /**< No special flags */
53 AVAHI_ENTRY_UNIQUE = 1, /**< The RRset is intended to be unique */
54 AVAHI_ENTRY_NOPROBE = 2, /**< Though the RRset is intended to be unique no probes shall be sent */
55 AVAHI_ENTRY_NOANNOUNCE = 4, /**< Do not announce this RR to other hosts */
56 AVAHI_ENTRY_ALLOWMUTIPLE = 8 /**< Allow multiple local records of this type, even if they are intended to be unique */
59 /** States of an entry group object */
61 AVAHI_ENTRY_GROUP_UNCOMMITED = -1, /**< The group has not yet been commited, the user must still call avahi_entry_group_commit() */
62 AVAHI_ENTRY_GROUP_REGISTERING = 0, /**< The entries of the group are currently being registered */
63 AVAHI_ENTRY_GROUP_ESTABLISHED, /**< The entries have successfully been established */
64 AVAHI_ENTRY_GROUP_COLLISION /**< A name collision for one of the entries in the group has been detected, the entries have been withdrawn */
65 } AvahiEntryGroupState;
67 /** Prototype for callback functions which are called whenever the state of an AvahiServer object changes */
68 typedef void (*AvahiServerCallback) (AvahiServer *s, AvahiServerState state, gpointer userdata);
70 /** Prototype for callback functions which are called whenever the state of an AvahiEntryGroup object changes */
71 typedef void (*AvahiEntryGroupCallback) (AvahiServer *s, AvahiEntryGroup *g, AvahiEntryGroupState state, gpointer userdata);
73 /** Stores configuration options for a server instance */
74 typedef struct AvahiServerConfig {
75 gchar *host_name; /**< Default host name. If left empty defaults to the result of gethostname(2) of the libc */
76 gchar *domain_name; /**< Default domain name. If left empty defaults to .local */
77 gboolean use_ipv4; /**< Enable IPv4 support */
78 gboolean use_ipv6; /**< Enable IPv6 support */
79 gboolean publish_hinfo; /**< Register a HINFO record for the host containing the local OS and CPU type */
80 gboolean publish_addresses; /**< Register A, AAAA and PTR records for all local IP addresses */
81 gboolean publish_workstation; /**< Register a _workstation._tcp service */
82 gboolean publish_domain; /**< Announce the local domain for browsing */
83 gboolean check_response_ttl; /**< If enabled the server ignores all incoming responses with IP TTL != 255 */
84 gboolean use_iff_running; /**< Require IFF_RUNNING on local network interfaces. This is the official way to check for link beat. Unfortunately this doesn't work with all drivers. So bettere leave this off. */
85 gboolean enable_reflector; /**< Reflect incoming mDNS traffic to all local networks. This allows mDNS based network browsing beyond ethernet borders */
86 gboolean reflect_ipv; /**< if enable_reflector is TRUE, enable/disable reflecting between IPv4 and IPv6 */
89 /** Allocate a new mDNS responder object. */
90 AvahiServer *avahi_server_new(
91 GMainContext *c, /**< The GLIB main loop context to attach to */
92 const AvahiServerConfig *sc, /**< If non-NULL a pointer to a configuration structure for the server. The server makes an internal deep copy of this structure, so you may free it using avahi_server_config_done() immediately after calling this function. */
93 AvahiServerCallback callback, /**< A callback which is called whenever the state of the server changes */
94 gpointer userdata /**< An opaque pointer which is passed to the callback function */);
96 /** Free an mDNS responder object */
97 void avahi_server_free(AvahiServer* s);
99 /** Fill in default values for a server configuration structure. If you
100 * make use of an AvahiServerConfig structure be sure to initialize
101 * it with this function for the sake of upwards library
102 * compatibility. This call may allocate strings on the heap. To
103 * release this memory make sure to call
104 * avahi_server_config_done(). If you want to replace any strings in
105 * the structure be sure to free the strings filled in by this
106 * function with g_free() first and allocate the replacements with
107 * g_malloc() (or g_strdup()).*/
108 AvahiServerConfig* avahi_server_config_init(
109 AvahiServerConfig *c /**< A structure which shall be filled in */ );
111 /** Make a deep copy of the configuration structure *c to *ret. */
112 AvahiServerConfig* avahi_server_config_copy(
113 AvahiServerConfig *ret /**< destination */,
114 const AvahiServerConfig *c /**< source */);
116 /** Free the data in a server configuration structure. */
117 void avahi_server_config_free(AvahiServerConfig *c);
119 /** Return the currently chosen domain name of the server object. The
120 * return value points to an internally allocated string. Be sure to
121 * make a copy of the string before calling any other library
123 const gchar* avahi_server_get_domain_name(AvahiServer *s);
125 /** Return the currently chosen host name. The return value points to a internally allocated string. */
126 const gchar* avahi_server_get_host_name(AvahiServer *s);
128 /** Return the currently chosen host name as a FQDN ("fully qualified
129 * domain name", i.e. the concatenation of the host and domain
130 * name). The return value points to a internally allocated string. */
131 const gchar* avahi_server_get_host_name_fqdn(AvahiServer *s);
133 /** Change the host name of a running mDNS responder. This will drop
134 all automicatilly generated RRs and readd them with the new
135 name. Since the responder has to probe for the new RRs this function
136 takes some time to take effect altough it returns immediately. This
137 function is intended to be called when a host name conflict is
138 reported using AvahiServerCallback. The caller should readd all user
139 defined RRs too since they otherwise continue to point to the outdated
141 gint avahi_server_set_host_name(AvahiServer *s, const gchar *host_name);
143 /** Change the domain name of a running mDNS responder. The same rules
144 * as with avahi_server_set_host_name() apply. */
145 gint avahi_server_set_domain_name(AvahiServer *s, const gchar *domain_name);
147 /** Return the opaque user data pointer attached to a server object */
148 gpointer avahi_server_get_data(AvahiServer *s);
150 /** Change the opaque user data pointer attached to a server object */
151 void avahi_server_set_data(AvahiServer *s, gpointer userdata);
153 /** Return the current state of the server object */
154 AvahiServerState avahi_server_get_state(AvahiServer *s);
156 /** Iterate through all local entries of the server. (when g is NULL)
157 * or of a specified entry group. At the first call state should point
158 * to a NULL initialized void pointer, That pointer is used to track
159 * the current iteration. It is not safe to call any other
160 * avahi_server_xxx() function during the iteration. If the last entry
161 * has been read, NULL is returned. */
162 const AvahiRecord *avahi_server_iterate(AvahiServer *s, AvahiEntryGroup *g, void **state);
164 /** Dump the current server status to the specified FILE object */
165 void avahi_server_dump(AvahiServer *s, FILE *f);
167 /** Create a new entry group. The specified callback function is
168 * called whenever the state of the group changes. Use entry group
169 * objects to keep track of you RRs. Add new RRs to a group using
170 * avahi_server_add_xxx(). Make sure to call avahi_entry_group_commit()
171 * to start the registration process for your RRs */
172 AvahiEntryGroup *avahi_entry_group_new(AvahiServer *s, AvahiEntryGroupCallback callback, gpointer userdata);
174 /** Free an entry group. All RRs assigned to the group are removed from the server */
175 void avahi_entry_group_free(AvahiEntryGroup *g);
177 /** Commit an entry group. This starts the probing and registration process for all RRs in the group */
178 gint avahi_entry_group_commit(AvahiEntryGroup *g);
180 /** Return the current state of the specified entry group */
181 AvahiEntryGroupState avahi_entry_group_get_state(AvahiEntryGroup *g);
183 /** Change the opaque user data pointer attached to an entry group object */
184 void avahi_entry_group_set_data(AvahiEntryGroup *g, gpointer userdata);
186 /** Return the opaque user data pointer currently set for the entry group object */
187 gpointer avahi_entry_group_get_data(AvahiEntryGroup *g);
189 gint avahi_server_add(
194 AvahiEntryFlags flags,
197 gint avahi_server_add_ptr(
202 AvahiEntryFlags flags,
206 gint avahi_server_add_address(
211 AvahiEntryFlags flags,
215 gint avahi_server_add_text(
220 AvahiEntryFlags flags,
222 ... /* text records, terminated by NULL */);
224 gint avahi_server_add_text_va(
229 AvahiEntryFlags flags,
233 gint avahi_server_add_text_strlst(
238 AvahiEntryFlags flags,
240 AvahiStringList *strlst);
242 gint avahi_server_add_service(
252 ... /* text records, terminated by NULL */);
254 gint avahi_server_add_service_va(
266 gint avahi_server_add_service_strlst(
276 AvahiStringList *strlst);
278 /** The type of DNS server */
280 AVAHI_DNS_SERVER_RESOLVE, /**< Unicast DNS servers for normal resolves (_domain._udp)*/
281 AVAHI_DNS_SERVER_UPDATE /**< Unicast DNS servers for updates (_dns-update._udp)*/
282 } AvahiDNSServerType;
284 /** Publish the specified unicast DNS server address via mDNS. You may
285 * browse for records create this way wit
286 * avahi_dns_server_browser_new(). */
287 gint avahi_server_add_dns_server_address(
293 AvahiDNSServerType type,
294 const AvahiAddress *address,
295 guint16 port /** should be 53 */);
297 /** Similar to avahi_server_add_dns_server_address(), but specify a
298 host name instead of an address. The specified host name should be
299 resolvable via mDNS */
300 gint avahi_server_add_dns_server_name(
306 AvahiDNSServerType type,
308 guint16 port /** should be 53 */);
311 AVAHI_BROWSER_NEW = 0,
312 AVAHI_BROWSER_REMOVE = -1
316 AVAHI_RESOLVER_FOUND = 0,
317 AVAHI_RESOLVER_TIMEOUT = -1
318 } AvahiResolverEvent;
321 typedef struct AvahiRecordBrowser AvahiRecordBrowser;
322 typedef void (*AvahiRecordBrowserCallback)(AvahiRecordBrowser *b, gint interface, guchar protocol, AvahiBrowserEvent event, AvahiRecord *record, gpointer userdata);
323 AvahiRecordBrowser *avahi_record_browser_new(AvahiServer *server, gint interface, guchar protocol, AvahiKey *key, AvahiRecordBrowserCallback callback, gpointer userdata);
324 void avahi_record_browser_free(AvahiRecordBrowser *b);
326 typedef struct AvahiHostNameResolver AvahiHostNameResolver;
327 typedef void (*AvahiHostNameResolverCallback)(AvahiHostNameResolver *r, gint interface, guchar protocol, AvahiResolverEvent event, const gchar *host_name, const AvahiAddress *a, gpointer userdata);
328 AvahiHostNameResolver *avahi_host_name_resolver_new(AvahiServer *server, gint interface, guchar protocol, const gchar *host_name, guchar aprotocol, AvahiHostNameResolverCallback calback, gpointer userdata);
329 void avahi_host_name_resolver_free(AvahiHostNameResolver *r);
331 typedef struct AvahiAddressResolver AvahiAddressResolver;
332 typedef void (*AvahiAddressResolverCallback)(AvahiAddressResolver *r, gint interface, guchar protocol, AvahiResolverEvent event, const AvahiAddress *a, const gchar *host_name, gpointer userdata);
333 AvahiAddressResolver *avahi_address_resolver_new(AvahiServer *server, gint interface, guchar protocol, const AvahiAddress *address, AvahiAddressResolverCallback calback, gpointer userdata);
334 void avahi_address_resolver_free(AvahiAddressResolver *r);
336 /** The type of domain to browse for */
338 AVAHI_DOMAIN_BROWSER_REGISTER, /**< Browse for a list of available registering domains */
339 AVAHI_DOMAIN_BROWSER_REGISTER_DEFAULT, /**< Browse for the default registering domain */
340 AVAHI_DOMAIN_BROWSER_BROWSE, /**< Browse for a list of available browsing domains */
341 AVAHI_DOMAIN_BROWSER_BROWSE_DEFAULT, /**< Browse for the default browsing domain */
342 AVAHI_DOMAIN_BROWSER_BROWSE_LEGACY /**< Legacy browse domain - see DNS-SD spec for more information */
343 } AvahiDomainBrowserType;
345 typedef struct AvahiDomainBrowser AvahiDomainBrowser;
346 typedef void (*AvahiDomainBrowserCallback)(AvahiDomainBrowser *b, gint interface, guchar protocol, AvahiBrowserEvent event, const gchar *domain, gpointer userdata);
347 AvahiDomainBrowser *avahi_domain_browser_new(AvahiServer *server, gint interface, guchar protocol, const gchar *domain, AvahiDomainBrowserType type, AvahiDomainBrowserCallback callback, gpointer userdata);
348 void avahi_domain_browser_free(AvahiDomainBrowser *b);
350 typedef struct AvahiServiceTypeBrowser AvahiServiceTypeBrowser;
351 typedef void (*AvahiServiceTypeBrowserCallback)(AvahiServiceTypeBrowser *b, gint interface, guchar protocol, AvahiBrowserEvent event, const gchar *type, const gchar *domain, gpointer userdata);
352 AvahiServiceTypeBrowser *avahi_service_type_browser_new(AvahiServer *server, gint interface, guchar protocol, const gchar *domain, AvahiServiceTypeBrowserCallback callback, gpointer userdata);
353 void avahi_service_type_browser_free(AvahiServiceTypeBrowser *b);
355 typedef struct AvahiServiceBrowser AvahiServiceBrowser;
356 typedef void (*AvahiServiceBrowserCallback)(AvahiServiceBrowser *b, gint interface, guchar protocol, AvahiBrowserEvent event, const gchar *name, const gchar *type, const gchar *domain, gpointer userdata);
357 AvahiServiceBrowser *avahi_service_browser_new(AvahiServer *server, gint interface, guchar protocol, const gchar *service_type, const gchar *domain, AvahiServiceBrowserCallback callback, gpointer userdata);
358 void avahi_service_browser_free(AvahiServiceBrowser *b);
360 typedef struct AvahiServiceResolver AvahiServiceResolver;
361 typedef void (*AvahiServiceResolverCallback)(AvahiServiceResolver *r, gint interface, guchar protocol, AvahiResolverEvent event, const gchar *name, const gchar *type, const gchar *domain, const gchar *host_name, const AvahiAddress *a, guint16 port, AvahiStringList *txt, gpointer userdata);
362 AvahiServiceResolver *avahi_service_resolver_new(AvahiServer *server, gint interface, guchar protocol, const gchar *name, const gchar *type, const gchar *domain, guchar aprotocol, AvahiServiceResolverCallback calback, gpointer userdata);
363 void avahi_service_resolver_free(AvahiServiceResolver *r);
366 /** A domain service browser object. Use this to browse for
367 * conventional unicast DNS servers which may be used to resolve
368 * conventional domain names */
369 typedef struct AvahiDNSServerBrowser AvahiDNSServerBrowser;
370 typedef void (*AvahiDNSServerBrowserCallback)(AvahiDNSServerBrowser *b, gint interface, guchar protocol, AvahiBrowserEvent event, const gchar *host_name, const AvahiAddress *a, guint16 port, gpointer userdata);
371 AvahiDNSServerBrowser *avahi_dns_server_browser_new(AvahiServer *server, gint interface, guchar protocol, const gchar *domain, AvahiDNSServerType type, guchar aprotocol, AvahiDNSServerBrowserCallback callback, gpointer userdata);
372 void avahi_dns_server_browser_free(AvahiDNSServerBrowser *b);