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