1#ifndef foolookuphfoo
2#define foolookuphfoo
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 avahi-core/lookup.h Functions for browsing/resolving services and other RRs */
26
27/** \example core-browse-services.c Example how to browse for DNS-SD
28 * services using an embedded mDNS stack. */
29
30/** A browsing object for arbitrary RRs */
31typedef struct AvahiSRecordBrowser AvahiSRecordBrowser;
32
33/** A host name to IP adddress resolver object */
34typedef struct AvahiSHostNameResolver AvahiSHostNameResolver;
35
36/** An IP address to host name resolver object ("reverse lookup") */
37typedef struct AvahiSAddressResolver AvahiSAddressResolver;
38
39/** A local domain browsing object. May be used to enumerate domains used on the local LAN */
40typedef struct AvahiSDomainBrowser AvahiSDomainBrowser;
41
42/** A DNS-SD service type browsing object. May be used to enumerate the service types of all available services on the local LAN */
43typedef struct AvahiSServiceTypeBrowser AvahiSServiceTypeBrowser;
44
45/** 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. */
46typedef struct AvahiSServiceBrowser AvahiSServiceBrowser;
47
48/** A DNS-SD service resolver.  Use this to retrieve addres, port and TXT data for a DNS-SD service */
49typedef struct AvahiSServiceResolver AvahiSServiceResolver;
50
51#include <avahi-common/cdecl.h>
52#include <avahi-common/defs.h>
53#include <avahi-core/core.h>
54
55AVAHI_C_DECL_BEGIN
56
57/** Callback prototype for AvahiSRecordBrowser events */
58typedef void (*AvahiSRecordBrowserCallback)(
59    AvahiSRecordBrowser *b,          /**< The AvahiSRecordBrowser object that is emitting this callback */
60    AvahiIfIndex interface,          /**< Logical OS network interface number the record was found on */
61    AvahiProtocol protocol,          /**< Protocol number the record was found. */
62    AvahiBrowserEvent event,         /**< Browsing event, either AVAHI_BROWSER_NEW or AVAHI_BROWSER_REMOVE */
63    AvahiRecord *record,             /**< The record that was found */
64    AvahiLookupResultFlags flags,  /**< Lookup flags */
65    void* userdata                   /**< Arbitrary user data passed to avahi_s_record_browser_new() */ );
66
67/** Create a new browsing object for arbitrary RRs */
68AvahiSRecordBrowser *avahi_s_record_browser_new(
69    AvahiServer *server,                    /**< The server object to which attach this query */
70    AvahiIfIndex interface,                 /**< Logical OS interface number where to look for the records, or AVAHI_IF_UNSPEC to look on interfaces */
71    AvahiProtocol protocol,                 /**< Protocol number to use when looking for the record, or AVAHI_PROTO_UNSPEC to look on all protocols */
72    AvahiKey *key,                          /**< The search key */
73    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. */
74    AvahiSRecordBrowserCallback callback,   /**< The callback to call on browsing events */
75    void* userdata                          /**< Arbitrary use suppliable data which is passed to the callback */);
76
77/** Free an AvahiSRecordBrowser object */
78void avahi_s_record_browser_free(AvahiSRecordBrowser *b);
79
80/** Callback prototype for AvahiSHostNameResolver events */
81typedef void (*AvahiSHostNameResolverCallback)(
82    AvahiSHostNameResolver *r,
83    AvahiIfIndex interface,
84    AvahiProtocol protocol,
85    AvahiResolverEvent event, /**< Resolving event */
86    const char *host_name,   /**< Host name which should be resolved. May differ in case from the query */
87    const AvahiAddress *a,    /**< The address, or NULL if the host name couldn't be resolved. */
88    AvahiLookupResultFlags flags,  /**< Lookup flags */
89    void* userdata);
90
91/** Create an AvahiSHostNameResolver object for resolving a host name to an adddress. See AvahiSRecordBrowser for more info on the paramters. */
92AvahiSHostNameResolver *avahi_s_host_name_resolver_new(
93    AvahiServer *server,
94    AvahiIfIndex interface,
95    AvahiProtocol protocol,
96    const char *host_name,                  /**< The host name to look for */
97    AvahiProtocol aprotocol,                /**< The address family of the desired address or AVAHI_PROTO_UNSPEC if doesn't matter. */
98    AvahiLookupFlags flags,                 /**< Lookup flags. */
99    AvahiSHostNameResolverCallback calback,
100    void* userdata);
101
102/** Free a AvahiSHostNameResolver object */
103void avahi_s_host_name_resolver_free(AvahiSHostNameResolver *r);
104
105/** Callback prototype for AvahiSAddressResolver events */
106typedef void (*AvahiSAddressResolverCallback)(
107    AvahiSAddressResolver *r,
108    AvahiIfIndex interface,
109    AvahiProtocol protocol,
110    AvahiResolverEvent event,
111    const AvahiAddress *a,
112    const char *host_name,   /**< A host name for the specified address, if one was found, i.e. event == AVAHI_RESOLVER_FOUND */
113    AvahiLookupResultFlags flags,  /**< Lookup flags */
114    void* userdata);
115
116/** Create an AvahiSAddressResolver object. See AvahiSRecordBrowser for more info on the paramters. */
117AvahiSAddressResolver *avahi_s_address_resolver_new(
118    AvahiServer *server,
119    AvahiIfIndex interface,
120    AvahiProtocol protocol,
121    const AvahiAddress *address,
122    AvahiLookupFlags flags,                 /**< Lookup flags. */
123    AvahiSAddressResolverCallback calback,
124    void* userdata);
125
126/** Free an AvahiSAddressResolver object */
127void avahi_s_address_resolver_free(AvahiSAddressResolver *r);
128
129/** Callback prototype for AvahiSDomainBrowser events */
130typedef void (*AvahiSDomainBrowserCallback)(
131    AvahiSDomainBrowser *b,
132    AvahiIfIndex interface,
133    AvahiProtocol protocol,
134    AvahiBrowserEvent event,
135    const char *domain,
136    AvahiLookupResultFlags flags,  /**< Lookup flags */
137    void* userdata);
138
139/** Create a new AvahiSDomainBrowser object */
140AvahiSDomainBrowser *avahi_s_domain_browser_new(
141    AvahiServer *server,
142    AvahiIfIndex interface,
143    AvahiProtocol protocol,
144    const char *domain,
145    AvahiDomainBrowserType type,
146    AvahiLookupFlags flags,                 /**< Lookup flags. */
147    AvahiSDomainBrowserCallback callback,
148    void* userdata);
149
150/** Free an AvahiSDomainBrowser object */
151void avahi_s_domain_browser_free(AvahiSDomainBrowser *b);
152
153/** Callback prototype for AvahiSServiceTypeBrowser events */
154typedef void (*AvahiSServiceTypeBrowserCallback)(
155    AvahiSServiceTypeBrowser *b,
156    AvahiIfIndex interface,
157    AvahiProtocol protocol,
158    AvahiBrowserEvent event,
159    const char *type,
160    const char *domain,
161    AvahiLookupResultFlags flags,  /**< Lookup flags */
162    void* userdata);
163
164/** Create a new AvahiSServiceTypeBrowser object. */
165AvahiSServiceTypeBrowser *avahi_s_service_type_browser_new(
166    AvahiServer *server,
167    AvahiIfIndex interface,
168    AvahiProtocol protocol,
169    const char *domain,
170    AvahiLookupFlags flags,                 /**< Lookup flags. */
171    AvahiSServiceTypeBrowserCallback callback,
172    void* userdata);
173
174/** Free an AvahiSServiceTypeBrowser object */
175void avahi_s_service_type_browser_free(AvahiSServiceTypeBrowser *b);
176
177/** Callback prototype for AvahiSServiceBrowser events */
178typedef void (*AvahiSServiceBrowserCallback)(
179    AvahiSServiceBrowser *b,
180    AvahiIfIndex interface,
181    AvahiProtocol protocol,
182    AvahiBrowserEvent event,
183    const char *name     /**< Service name, e.g. "Lennart's Files" */,
184    const char *type     /**< DNS-SD type, e.g. "_http._tcp" */,
185    const char *domain   /**< Domain of this service, e.g. "local" */,
186    AvahiLookupResultFlags flags,  /**< Lookup flags */
187    void* userdata);
188
189/** Create a new AvahiSServiceBrowser object. */
190AvahiSServiceBrowser *avahi_s_service_browser_new(
191    AvahiServer *server,
192    AvahiIfIndex interface,
193    AvahiProtocol protocol,
194    const char *service_type /** DNS-SD service type, e.g. "_http._tcp" */,
195    const char *domain,
196    AvahiLookupFlags flags,                 /**< Lookup flags. */
197    AvahiSServiceBrowserCallback callback,
198    void* userdata);
199
200/** Free an AvahiSServiceBrowser object */
201void avahi_s_service_browser_free(AvahiSServiceBrowser *b);
202
203/** Callback prototype for AvahiSServiceResolver events */
204typedef void (*AvahiSServiceResolverCallback)(
205    AvahiSServiceResolver *r,
206    AvahiIfIndex interface,
207    AvahiProtocol protocol,
208    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. */
209    const char *name,       /**< Service name */
210    const char *type,       /**< Service Type */
211    const char *domain,
212    const char *host_name,  /**< Host name of the service */
213    const AvahiAddress *a,   /**< The resolved host name */
214    uint16_t port,            /**< Service name */
215    AvahiStringList *txt,    /**< TXT record data */
216    AvahiLookupResultFlags flags,  /**< Lookup flags */
217    void* userdata);
218
219/** Create a new AvahiSServiceResolver object. The specified callback function will be called with the resolved service data. */
220AvahiSServiceResolver *avahi_s_service_resolver_new(
221    AvahiServer *server,
222    AvahiIfIndex interface,
223    AvahiProtocol protocol,
224    const char *name,
225    const char *type,
226    const char *domain,
227    AvahiProtocol aprotocol,    /**< Address family of the desired service address. Use AVAHI_PROTO_UNSPEC if you don't care */
228    AvahiLookupFlags flags,                 /**< Lookup flags. */
229    AvahiSServiceResolverCallback calback,
230    void* userdata);
231
232/** Free an AvahiSServiceResolver object */
233void avahi_s_service_resolver_free(AvahiSServiceResolver *r);
234
235AVAHI_C_DECL_END
236
237#endif
238