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
25 /** \file lookup.h Functions for browsing/resolving services and other RRs */
27 /** \example core-browse-services.c Example how to browse for DNS-SD
28 * services using an embedded mDNS stack. */
30 #include <avahi-common/cdecl.h>
31 #include <avahi-common/defs.h>
33 #ifndef DOXYGEN_SHOULD_SKIP_THIS
37 /** A browsing object for arbitrary RRs */
38 typedef struct AvahiSRecordBrowser AvahiSRecordBrowser;
40 /** A host name to IP adddress resolver object */
41 typedef struct AvahiSHostNameResolver AvahiSHostNameResolver;
43 /** An IP address to host name resolver object ("reverse lookup") */
44 typedef struct AvahiSAddressResolver AvahiSAddressResolver;
46 /** A local domain browsing object. May be used to enumerate domains used on the local LAN */
47 typedef struct AvahiSDomainBrowser AvahiSDomainBrowser;
49 /** A DNS-SD service type browsing object. May be used to enumerate the service types of all available services on the local LAN */
50 typedef struct AvahiSServiceTypeBrowser AvahiSServiceTypeBrowser;
52 /** A DNS-SD service browser. Use this to enumerate available services of a certain kind on the local LAN. Use AvahiSServiceResolver to get specific service data like address and port for a service. */
53 typedef struct AvahiSServiceBrowser AvahiSServiceBrowser;
55 /** A DNS-SD service resolver. Use this to retrieve addres, port and TXT data for a DNS-SD service */
56 typedef struct AvahiSServiceResolver AvahiSServiceResolver;
58 /** A domain service browser object. Use this to browse for
59 * conventional unicast DNS servers which may be used to resolve
60 * conventional domain names */
61 typedef struct AvahiSDNSServerBrowser AvahiSDNSServerBrowser;
63 #ifndef DOXYGEN_SHOULD_SKIP_THIS
70 #ifndef DOXYGEN_SHOULD_SKIP_THIS
75 /** Callback prototype for AvahiSRecordBrowser events */
76 typedef void (*AvahiSRecordBrowserCallback)(
77 AvahiSRecordBrowser *b, /**< The AvahiSRecordBrowser object that is emitting this callback */
78 AvahiIfIndex interface, /**< Logical OS network interface number the record was found on */
79 AvahiProtocol protocol, /**< Protocol number the record was found. */
80 AvahiBrowserEvent event, /**< Browsing event, either AVAHI_BROWSER_NEW or AVAHI_BROWSER_REMOVE */
81 AvahiRecord *record, /**< The record that was found */
82 AvahiLookupResultFlags flags, /**< Lookup flags */
83 void* userdata /**< Arbitrary user data passed to avahi_s_record_browser_new() */ );
85 /** Create a new browsing object for arbitrary RRs */
86 AvahiSRecordBrowser *avahi_s_record_browser_new(
87 AvahiServer *server, /**< The server object to which attach this query */
88 AvahiIfIndex interface, /**< Logical OS interface number where to look for the records, or AVAHI_IF_UNSPEC to look on interfaces */
89 AvahiProtocol protocol, /**< Protocol number to use when looking for the record, or AVAHI_PROTO_UNSPEC to look on all protocols */
90 AvahiKey *key, /**< The search key */
91 AvahiLookupFlags flags, /**< Lookup flags. Must have set either AVAHI_LOOKUP_FORCE_WIDE_AREA or AVAHI_LOOKUP_FORCE_MULTICAST, since domain based detection is not available here. */
92 AvahiSRecordBrowserCallback callback, /**< The callback to call on browsing events */
93 void* userdata /**< Arbitrary use suppliable data which is passed to the callback */);
95 /** Free an AvahiSRecordBrowser object */
96 void avahi_s_record_browser_free(AvahiSRecordBrowser *b);
98 /** Callback prototype for AvahiSHostNameResolver events */
99 typedef void (*AvahiSHostNameResolverCallback)(
100 AvahiSHostNameResolver *r,
101 AvahiIfIndex interface,
102 AvahiProtocol protocol,
103 AvahiResolverEvent event, /**< Resolving event */
104 const char *host_name, /**< Host name which should be resolved. May differ in case from the query */
105 const AvahiAddress *a, /**< The address, or NULL if the host name couldn't be resolved. */
106 AvahiLookupResultFlags flags, /**< Lookup flags */
109 /** Create an AvahiSHostNameResolver object for resolving a host name to an adddress. See AvahiSRecordBrowser for more info on the paramters. */
110 AvahiSHostNameResolver *avahi_s_host_name_resolver_new(
112 AvahiIfIndex interface,
113 AvahiProtocol protocol,
114 const char *host_name, /**< The host name to look for */
115 AvahiProtocol aprotocol, /**< The address family of the desired address or AVAHI_PROTO_UNSPEC if doesn't matter. */
116 AvahiLookupFlags flags, /**< Lookup flags. */
117 AvahiSHostNameResolverCallback calback,
120 /** Free a AvahiSHostNameResolver object */
121 void avahi_s_host_name_resolver_free(AvahiSHostNameResolver *r);
123 /** Callback prototype for AvahiSAddressResolver events */
124 typedef void (*AvahiSAddressResolverCallback)(
125 AvahiSAddressResolver *r,
126 AvahiIfIndex interface,
127 AvahiProtocol protocol,
128 AvahiResolverEvent event,
129 const AvahiAddress *a,
130 const char *host_name, /**< A host name for the specified address, if one was found, i.e. event == AVAHI_RESOLVER_FOUND */
131 AvahiLookupResultFlags flags, /**< Lookup flags */
134 /** Create an AvahiSAddressResolver object. See AvahiSRecordBrowser for more info on the paramters. */
135 AvahiSAddressResolver *avahi_s_address_resolver_new(
137 AvahiIfIndex interface,
138 AvahiProtocol protocol,
139 const AvahiAddress *address,
140 AvahiLookupFlags flags, /**< Lookup flags. */
141 AvahiSAddressResolverCallback calback,
144 /** Free an AvahiSAddressResolver object */
145 void avahi_s_address_resolver_free(AvahiSAddressResolver *r);
147 /** Callback prototype for AvahiSDomainBrowser events */
148 typedef void (*AvahiSDomainBrowserCallback)(
149 AvahiSDomainBrowser *b,
150 AvahiIfIndex interface,
151 AvahiProtocol protocol,
152 AvahiBrowserEvent event,
154 AvahiLookupResultFlags flags, /**< Lookup flags */
157 /** Create a new AvahiSDomainBrowser object */
158 AvahiSDomainBrowser *avahi_s_domain_browser_new(
160 AvahiIfIndex interface,
161 AvahiProtocol protocol,
163 AvahiDomainBrowserType type,
164 AvahiLookupFlags flags, /**< Lookup flags. */
165 AvahiSDomainBrowserCallback callback,
168 /** Free an AvahiSDomainBrowser object */
169 void avahi_s_domain_browser_free(AvahiSDomainBrowser *b);
171 /** Callback prototype for AvahiSServiceTypeBrowser events */
172 typedef void (*AvahiSServiceTypeBrowserCallback)(
173 AvahiSServiceTypeBrowser *b,
174 AvahiIfIndex interface,
175 AvahiProtocol protocol,
176 AvahiBrowserEvent event,
179 AvahiLookupResultFlags flags, /**< Lookup flags */
182 /** Create a new AvahiSServiceTypeBrowser object. */
183 AvahiSServiceTypeBrowser *avahi_s_service_type_browser_new(
185 AvahiIfIndex interface,
186 AvahiProtocol protocol,
188 AvahiLookupFlags flags, /**< Lookup flags. */
189 AvahiSServiceTypeBrowserCallback callback,
192 /** Free an AvahiSServiceTypeBrowser object */
193 void avahi_s_service_type_browser_free(AvahiSServiceTypeBrowser *b);
195 /** Callback prototype for AvahiSServiceBrowser events */
196 typedef void (*AvahiSServiceBrowserCallback)(
197 AvahiSServiceBrowser *b,
198 AvahiIfIndex interface,
199 AvahiProtocol protocol,
200 AvahiBrowserEvent event,
201 const char *name /**< Service name, e.g. "Lennart's Files" */,
202 const char *type /**< DNS-SD type, e.g. "_http._tcp" */,
203 const char *domain /**< Domain of this service, e.g. "local" */,
204 AvahiLookupResultFlags flags, /**< Lookup flags */
207 /** Create a new AvahiSServiceBrowser object. */
208 AvahiSServiceBrowser *avahi_s_service_browser_new(
210 AvahiIfIndex interface,
211 AvahiProtocol protocol,
212 const char *service_type /** DNS-SD service type, e.g. "_http._tcp" */,
214 AvahiLookupFlags flags, /**< Lookup flags. */
215 AvahiSServiceBrowserCallback callback,
218 /** Free an AvahiSServiceBrowser object */
219 void avahi_s_service_browser_free(AvahiSServiceBrowser *b);
221 /** Callback prototype for AvahiSServiceResolver events */
222 typedef void (*AvahiSServiceResolverCallback)(
223 AvahiSServiceResolver *r,
224 AvahiIfIndex interface,
225 AvahiProtocol protocol,
226 AvahiResolverEvent event, /**< Is AVAHI_RESOLVER_FOUND when the service was resolved successfully, and everytime it changes. Is AVAHI_RESOLVER_TIMOUT when the service failed to resolve or disappeared. */
227 const char *name, /**< Service name */
228 const char *type, /**< Service Type */
230 const char *host_name, /**< Host name of the service */
231 const AvahiAddress *a, /**< The resolved host name */
232 uint16_t port, /**< Service name */
233 AvahiStringList *txt, /**< TXT record data */
234 AvahiLookupResultFlags flags, /**< Lookup flags */
237 /** Create a new AvahiSServiceResolver object. The specified callback function will be called with the resolved service data. */
238 AvahiSServiceResolver *avahi_s_service_resolver_new(
240 AvahiIfIndex interface,
241 AvahiProtocol protocol,
245 AvahiProtocol aprotocol, /**< Address family of the desired service address. Use AVAHI_PROTO_UNSPEC if you don't care */
246 AvahiLookupFlags flags, /**< Lookup flags. */
247 AvahiSServiceResolverCallback calback,
250 /** Free an AvahiSServiceResolver object */
251 void avahi_s_service_resolver_free(AvahiSServiceResolver *r);
253 /** Callback prototype for AvahiSDNSServerBrowser events */
254 typedef void (*AvahiSDNSServerBrowserCallback)(
255 AvahiSDNSServerBrowser *b,
256 AvahiIfIndex interface,
257 AvahiProtocol protocol,
258 AvahiBrowserEvent event,
259 const char *host_name, /**< Host name of the DNS server, probably useless */
260 const AvahiAddress *a, /**< Address of the DNS server */
261 uint16_t port, /**< Port number of the DNS servers, probably 53 */
262 AvahiLookupResultFlags flags, /**< Lookup flags */
265 /** Create a new AvahiSDNSServerBrowser object */
266 AvahiSDNSServerBrowser *avahi_s_dns_server_browser_new(
268 AvahiIfIndex interface,
269 AvahiProtocol protocol,
271 AvahiDNSServerType type,
272 AvahiProtocol aprotocol, /**< Address protocol for the DNS server */
273 AvahiLookupFlags flags, /**< Lookup flags. */
274 AvahiSDNSServerBrowserCallback callback,
277 /** Free an AvahiSDNSServerBrowser object */
278 void avahi_s_dns_server_browser_free(AvahiSDNSServerBrowser *b);
280 #ifndef DOXYGEN_SHOULD_SKIP_THIS