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
27 #include <avahi-common/cdecl.h>
28 #include <avahi-common/address.h>
29 #include <avahi-common/strlst.h>
30 #include <avahi-common/defs.h>
31 #include <avahi-common/watch.h>
32 #include <avahi-common/gccmacro.h>
34 /** \file client.h Definitions and functions for the client API over D-Bus */
36 /** \example client-publish-service.c Example how to register a DNS-SD
37 * service using the client interface to avahi-daemon. It behaves like a network
38 * printer registering both an IPP and a BSD LPR service. */
40 /** \example client-browse-services.c Example how to browse for DNS-SD
41 * services using the client interface to avahi-daemon. */
43 /** \example glib-integration.c Example of how to integrate
44 * avahi use with GLIB/GTK applications */
47 #ifndef DOXYGEN_SHOULD_SKIP_THIS
51 /** A connection context */
52 typedef struct AvahiClient AvahiClient;
54 /** An entry group object */
55 typedef struct AvahiEntryGroup AvahiEntryGroup;
57 /** A domain browser object */
58 typedef struct AvahiDomainBrowser AvahiDomainBrowser;
60 /** A service browser object */
61 typedef struct AvahiServiceBrowser AvahiServiceBrowser;
63 /** A service type browser object */
64 typedef struct AvahiServiceTypeBrowser AvahiServiceTypeBrowser;
66 /** A service resolver object */
67 typedef struct AvahiServiceResolver AvahiServiceResolver;
69 /** A service resolver object */
70 typedef struct AvahiHostNameResolver AvahiHostNameResolver;
72 /** An address resolver object */
73 typedef struct AvahiAddressResolver AvahiAddressResolver;
75 /** States of a client object, a superset of AvahiServerState */
77 AVAHI_CLIENT_S_INVALID = AVAHI_SERVER_INVALID,
78 AVAHI_CLIENT_S_REGISTERING = AVAHI_SERVER_REGISTERING,
79 AVAHI_CLIENT_S_RUNNING = AVAHI_SERVER_RUNNING,
80 AVAHI_CLIENT_S_COLLISION = AVAHI_SERVER_COLLISION,
81 AVAHI_CLIENT_DISCONNECTED = 100 /**< Lost DBUS connection to the Avahi daemon */
84 /** The function prototype for the callback of an AvahiClient */
85 typedef void (*AvahiClientCallback) (AvahiClient *s, AvahiClientState state, void* userdata);
87 /** The function prototype for the callback of an AvahiEntryGroup */
88 typedef void (*AvahiEntryGroupCallback) (AvahiEntryGroup *g, AvahiEntryGroupState state, void* userdata);
90 /** The function prototype for the callback of an AvahiDomainBrowser */
91 typedef void (*AvahiDomainBrowserCallback) (AvahiDomainBrowser *b, AvahiIfIndex interface, AvahiProtocol protocol, AvahiBrowserEvent event, const char *domain, void *userdata);
93 /** The function prototype for the callback of an AvahiServiceBrowser */
94 typedef void (*AvahiServiceBrowserCallback) (AvahiServiceBrowser *b, AvahiIfIndex interface, AvahiProtocol protocol, AvahiBrowserEvent event, const char *name, const char *type, const char *domain, void *userdata);
96 /** The function prototype for the callback of an AvahiServiceTypeBrowser */
97 typedef void (*AvahiServiceTypeBrowserCallback) (AvahiServiceTypeBrowser *b, AvahiIfIndex interface, AvahiProtocol protocol, AvahiBrowserEvent event, const char *type, const char *domain, void *userdata);
99 /** The function prototype for the callback of an AvahiServiceResolver */
100 typedef void (*AvahiServiceResolverCallback) (
101 AvahiServiceResolver *r,
102 AvahiIfIndex interface,
103 AvahiProtocol protocol,
104 AvahiResolverEvent event,
108 const char *host_name,
109 const AvahiAddress *a,
111 AvahiStringList *txt,
114 /** The function prototype for the callback of an AvahiHostNameResolver */
115 typedef void (*AvahiHostNameResolverCallback) (
116 AvahiHostNameResolver *r,
117 AvahiIfIndex interface,
118 AvahiProtocol protocol,
119 AvahiResolverEvent event,
121 const AvahiAddress *a,
124 /** The function prototype for the callback of an AvahiAddressResolver */
125 typedef void (*AvahiAddressResolverCallback) (
126 AvahiAddressResolver *r,
127 AvahiIfIndex interface,
128 AvahiProtocol protocol,
129 AvahiResolverEvent event,
130 AvahiProtocol aprotocol,
131 const AvahiAddress *a,
135 /** Creates a new client instance */
136 AvahiClient* avahi_client_new (const AvahiPoll *poll_api, AvahiClientCallback callback, void *userdata, int *error);
138 /** Free a client instance */
139 void avahi_client_free(AvahiClient *client);
141 /** Get the version of the server */
142 const char* avahi_client_get_version_string (AvahiClient*);
145 const char* avahi_client_get_host_name (AvahiClient*);
147 /** Get domain name */
148 const char* avahi_client_get_domain_name (AvahiClient*);
150 /** Get FQDN domain name */
151 const char* avahi_client_get_host_name_fqdn (AvahiClient*);
154 AvahiClientState avahi_client_get_state(AvahiClient *client);
156 /** Get the last error number */
157 int avahi_client_errno (AvahiClient*);
159 /** Create a new AvahiEntryGroup object */
160 AvahiEntryGroup* avahi_entry_group_new (AvahiClient*, AvahiEntryGroupCallback callback, void *userdata);
162 /** Clean up and free an AvahiEntryGroup object */
163 int avahi_entry_group_free (AvahiEntryGroup *);
165 /** Commit an AvahiEntryGroup */
166 int avahi_entry_group_commit (AvahiEntryGroup*);
168 /** Reset an AvahiEntryGroup */
169 int avahi_entry_group_reset (AvahiEntryGroup*);
171 /** Get an AvahiEntryGroup's state */
172 int avahi_entry_group_get_state (AvahiEntryGroup*);
174 /** Check if an AvahiEntryGroup is empty */
175 int avahi_entry_group_is_empty (AvahiEntryGroup*);
177 /** Get an AvahiEntryGroup's owning client instance */
178 AvahiClient* avahi_entry_group_get_client (AvahiEntryGroup*);
180 /** Add a service, takes a variable NULL terminated list of text records */
181 int avahi_entry_group_add_service(
182 AvahiEntryGroup *group,
183 AvahiIfIndex interface,
184 AvahiProtocol protocol,
190 ...) AVAHI_GCC_SENTINEL;
192 /** Add a service, takes an AvahiStringList for text records */
193 int avahi_entry_group_add_service_strlst(
194 AvahiEntryGroup *group,
195 AvahiIfIndex interface,
196 AvahiProtocol protocol,
202 AvahiStringList *txt);
204 /** Add a service, takes a NULL terminated va_list for text records */
205 int avahi_entry_group_add_service_va(
206 AvahiEntryGroup *group,
207 AvahiIfIndex interface,
208 AvahiProtocol protocol,
216 /** Get the D-Bus path of an AvahiEntryGroup object, for debugging purposes only. */
217 const char* avahi_entry_group_get_dbus_path (AvahiEntryGroup *);
219 /** Browse for domains on the local network */
220 AvahiDomainBrowser* avahi_domain_browser_new (AvahiClient *client,
221 AvahiIfIndex interface,
222 AvahiProtocol protocol,
224 AvahiDomainBrowserType btype,
225 AvahiDomainBrowserCallback callback,
228 /** Get the parent client of an AvahiDomainBrowser object */
229 AvahiClient* avahi_domain_browser_get_client (AvahiDomainBrowser *);
231 /** Get the D-Bus path of an AvahiDomainBrowser object, for debugging purposes only. */
232 const char* avahi_domain_browser_get_dbus_path (AvahiDomainBrowser *);
234 /** Cleans up and frees an AvahiDomainBrowser object */
235 int avahi_domain_browser_free (AvahiDomainBrowser *);
237 /** Browse for service types on the local network */
238 AvahiServiceTypeBrowser* avahi_service_type_browser_new (
240 AvahiIfIndex interface,
241 AvahiProtocol protocol,
243 AvahiServiceTypeBrowserCallback callback,
246 /** Get the parent client of an AvahiServiceTypeBrowser object */
247 AvahiClient* avahi_service_type_browser_get_client (AvahiServiceTypeBrowser *);
249 /** Get the D-Bus path of an AvahiServiceTypeBrowser object, for debugging purposes only. */
250 const char* avahi_service_type_browser_get_dbus_path(AvahiServiceTypeBrowser *);
252 /** Cleans up and frees an AvahiServiceTypeBrowser object */
253 int avahi_service_type_browser_free (AvahiServiceTypeBrowser *);
255 /** Browse for services of a type on the local network */
256 AvahiServiceBrowser* avahi_service_browser_new (
258 AvahiIfIndex interface,
259 AvahiProtocol protocol,
262 AvahiServiceBrowserCallback callback,
265 /** Get the D-Bus path of an AvahiServiceBrowser object, for debugging purposes only. */
266 const char* avahi_service_browser_get_dbus_path (AvahiServiceBrowser *);
268 /** Get the parent client of an AvahiServiceBrowser object */
269 AvahiClient* avahi_service_browser_get_client (AvahiServiceBrowser *);
271 /* Cleans up and frees an AvahiServiceBrowser object */
272 int avahi_service_browser_free (AvahiServiceBrowser *);
274 /** Create a new service resolver object */
275 AvahiServiceResolver * avahi_service_resolver_new(
277 AvahiIfIndex interface,
278 AvahiProtocol protocol,
282 AvahiProtocol aprotocol,
283 AvahiServiceResolverCallback callback,
286 /** Get the parent client of an AvahiServiceResolver object */
287 AvahiClient* avahi_service_resolver_get_client (AvahiServiceResolver *);
289 /** Free a service resolver object */
290 int avahi_service_resolver_free(AvahiServiceResolver *r);
292 /** Block until the resolving is complete */
293 int avahi_service_resolver_block(AvahiServiceResolver *r);
295 /** Create a new hostname resolver object */
296 AvahiHostNameResolver * avahi_host_name_resolver_new(
298 AvahiIfIndex interface,
299 AvahiProtocol protocol,
301 AvahiProtocol aprotocol,
302 AvahiHostNameResolverCallback callback,
305 /** Get the parent client of an AvahiHostNameResolver object */
306 AvahiClient* avahi_host_name_resolver_get_client (AvahiHostNameResolver *);
308 /** Free a hostname resolver object */
309 int avahi_host_name_resolver_free(AvahiHostNameResolver *r);
311 /** Block until the resolving is complete */
312 int avahi_host_name_resolver_block(AvahiHostNameResolver *r);
314 /** Create a new address resolver object from an address string. Set aprotocol to AF_UNSPEC for protocol detection. */
315 AvahiAddressResolver * avahi_address_resolver_new(
317 AvahiIfIndex interface,
318 AvahiProtocol protocol,
320 AvahiAddressResolverCallback callback,
323 /** Create a new address resolver object from an AvahiAddress object */
324 AvahiAddressResolver* avahi_address_resolver_new_a(
326 AvahiIfIndex interface,
327 AvahiProtocol protocol,
328 const AvahiAddress *a,
329 AvahiAddressResolverCallback callback,
332 /** Get the parent client of an AvahiAddressResolver object */
333 AvahiClient* avahi_address_resolver_get_client (AvahiAddressResolver *);
335 /** Free a AvahiAddressResolver resolver object */
336 int avahi_address_resolver_free(AvahiAddressResolver *r);
338 /** Block until the resolving is complete */
339 int avahi_address_resolver_block(AvahiAddressResolver *r);
341 #ifndef DOXYGEN_SHOULD_SKIP_THIS