git.meshlink.io Git - catta/blob - avahi-core/lookup.h

   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 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 #include <avahi-common/cdecl.h>
  31 #include <avahi-common/defs.h>
  32
  33 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  34 AVAHI_C_DECL_BEGIN
  35 #endif
  36
  37 /** A browsing object for arbitrary RRs */
  38 typedef struct AvahiSRecordBrowser AvahiSRecordBrowser;
  39
  40 /** A host name to IP adddress resolver object */
  41 typedef struct AvahiSHostNameResolver AvahiSHostNameResolver;
  42
  43 /** An IP address to host name resolver object ("reverse lookup") */
  44 typedef struct AvahiSAddressResolver AvahiSAddressResolver;
  45
  46 /** A local domain browsing object. May be used to enumerate domains used on the local LAN */
  47 typedef struct AvahiSDomainBrowser AvahiSDomainBrowser;
  48
  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;
  51
  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;
  54
  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;
  57
  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;
  62
  63 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  64 AVAHI_C_DECL_END
  65 #endif
  66
  67 #include "core.h"
  68 #include "publish.h"
  69
  70 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  71 AVAHI_C_DECL_BEGIN
  72 #endif
  73
  74
  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() */ );
  84
  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 */);
  94
  95 /** Free an AvahiSRecordBrowser object */
  96 void avahi_s_record_browser_free(AvahiSRecordBrowser *b);
  97
  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 */
 107     void* userdata);
 108
 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(
 111     AvahiServer *server,
 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,
 118     void* userdata);
 119
 120 /** Free a AvahiSHostNameResolver object */
 121 void avahi_s_host_name_resolver_free(AvahiSHostNameResolver *r);
 122
 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 */
 132     void* userdata);
 133
 134 /** Create an AvahiSAddressResolver object. See AvahiSRecordBrowser for more info on the paramters. */
 135 AvahiSAddressResolver *avahi_s_address_resolver_new(
 136     AvahiServer *server,
 137     AvahiIfIndex interface,
 138     AvahiProtocol protocol,
 139     const AvahiAddress *address,
 140     AvahiLookupFlags flags,                 /**< Lookup flags. */
 141     AvahiSAddressResolverCallback calback,
 142     void* userdata);
 143
 144 /** Free an AvahiSAddressResolver object */
 145 void avahi_s_address_resolver_free(AvahiSAddressResolver *r);
 146
 147 /** Callback prototype for AvahiSDomainBrowser events */
 148 typedef void (*AvahiSDomainBrowserCallback)(
 149     AvahiSDomainBrowser *b,
 150     AvahiIfIndex interface,
 151     AvahiProtocol protocol,
 152     AvahiBrowserEvent event,
 153     const char *domain,
 154     AvahiLookupResultFlags flags,  /**< Lookup flags */
 155     void* userdata);
 156
 157 /** Create a new AvahiSDomainBrowser object */
 158 AvahiSDomainBrowser *avahi_s_domain_browser_new(
 159     AvahiServer *server,
 160     AvahiIfIndex interface,
 161     AvahiProtocol protocol,
 162     const char *domain,
 163     AvahiDomainBrowserType type,
 164     AvahiLookupFlags flags,                 /**< Lookup flags. */
 165     AvahiSDomainBrowserCallback callback,
 166     void* userdata);
 167
 168 /** Free an AvahiSDomainBrowser object */
 169 void avahi_s_domain_browser_free(AvahiSDomainBrowser *b);
 170
 171 /** Callback prototype for AvahiSServiceTypeBrowser events */
 172 typedef void (*AvahiSServiceTypeBrowserCallback)(
 173     AvahiSServiceTypeBrowser *b,
 174     AvahiIfIndex interface,
 175     AvahiProtocol protocol,
 176     AvahiBrowserEvent event,
 177     const char *type,
 178     const char *domain,
 179     AvahiLookupResultFlags flags,  /**< Lookup flags */
 180     void* userdata);
 181
 182 /** Create a new AvahiSServiceTypeBrowser object. */
 183 AvahiSServiceTypeBrowser *avahi_s_service_type_browser_new(
 184     AvahiServer *server,
 185     AvahiIfIndex interface,
 186     AvahiProtocol protocol,
 187     const char *domain,
 188     AvahiLookupFlags flags,                 /**< Lookup flags. */
 189     AvahiSServiceTypeBrowserCallback callback,
 190     void* userdata);
 191
 192 /** Free an AvahiSServiceTypeBrowser object */
 193 void avahi_s_service_type_browser_free(AvahiSServiceTypeBrowser *b);
 194
 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 */
 205     void* userdata);
 206
 207 /** Create a new AvahiSServiceBrowser object. */
 208 AvahiSServiceBrowser *avahi_s_service_browser_new(
 209     AvahiServer *server,
 210     AvahiIfIndex interface,
 211     AvahiProtocol protocol,
 212     const char *service_type /** DNS-SD service type, e.g. "_http._tcp" */,
 213     const char *domain,
 214     AvahiLookupFlags flags,                 /**< Lookup flags. */
 215     AvahiSServiceBrowserCallback callback,
 216     void* userdata);
 217
 218 /** Free an AvahiSServiceBrowser object */
 219 void avahi_s_service_browser_free(AvahiSServiceBrowser *b);
 220
 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 */
 229     const char *domain,
 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 */
 235     void* userdata);
 236
 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(
 239     AvahiServer *server,
 240     AvahiIfIndex interface,
 241     AvahiProtocol protocol,
 242     const char *name,
 243     const char *type,
 244     const char *domain,
 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,
 248     void* userdata);
 249
 250 /** Free an AvahiSServiceResolver object */
 251 void avahi_s_service_resolver_free(AvahiSServiceResolver *r);
 252
 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 */
 263     void* userdata);
 264
 265 /** Create a new AvahiSDNSServerBrowser object */
 266 AvahiSDNSServerBrowser *avahi_s_dns_server_browser_new(
 267     AvahiServer *server,
 268     AvahiIfIndex interface,
 269     AvahiProtocol protocol,
 270     const char *domain,
 271     AvahiDNSServerType type,
 272     AvahiProtocol aprotocol,  /**< Address protocol for the DNS server */
 273     AvahiLookupFlags flags,                 /**< Lookup flags. */
 274     AvahiSDNSServerBrowserCallback callback,
 275     void* userdata);
 276
 277 /** Free an AvahiSDNSServerBrowser object */
 278 void avahi_s_dns_server_browser_free(AvahiSDNSServerBrowser *b);
 279
 280 #ifndef DOXYGEN_SHOULD_SKIP_THIS
 281 AVAHI_C_DECL_END
 282 #endif
 283
 284 #endif