Home | History | Annotate | Download | only in avahi-core
      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 */
     29 typedef struct AvahiSRecordBrowser AvahiSRecordBrowser;
     30 
     31 /** A host name to IP adddress resolver object */
     32 typedef struct AvahiSHostNameResolver AvahiSHostNameResolver;
     33 
     34 /** An IP address to host name resolver object ("reverse lookup") */
     35 typedef struct AvahiSAddressResolver AvahiSAddressResolver;
     36 
     37 /** A local domain browsing object. May be used to enumerate domains used on the local LAN */
     38 typedef 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 */
     41 typedef 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. */
     44 typedef struct AvahiSServiceBrowser AvahiSServiceBrowser;
     45 
     46 /** A DNS-SD service resolver.  Use this to retrieve addres, port and TXT data for a DNS-SD service */
     47 typedef struct AvahiSServiceResolver AvahiSServiceResolver;
     48 
     49 #include <avahi-common/cdecl.h>
     50 #include <avahi-common/defs.h>
     51 #include <avahi-core/core.h>
     52 
     53 AVAHI_C_DECL_BEGIN
     54 
     55 /** Callback prototype for AvahiSRecordBrowser events */
     56 typedef 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 */
     66 AvahiSRecordBrowser *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 */
     76 void avahi_s_record_browser_free(AvahiSRecordBrowser *b);
     77 
     78 /** Callback prototype for AvahiSHostNameResolver events */
     79 typedef 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. */
     90 AvahiSHostNameResolver *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 */
    101 void avahi_s_host_name_resolver_free(AvahiSHostNameResolver *r);
    102 
    103 /** Callback prototype for AvahiSAddressResolver events */
    104 typedef 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. */
    115 AvahiSAddressResolver *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 */
    125 void avahi_s_address_resolver_free(AvahiSAddressResolver *r);
    126 
    127 /** Callback prototype for AvahiSDomainBrowser events */
    128 typedef 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 */
    138 AvahiSDomainBrowser *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 */
    149 void avahi_s_domain_browser_free(AvahiSDomainBrowser *b);
    150 
    151 /** Callback prototype for AvahiSServiceTypeBrowser events */
    152 typedef 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. */
    163 AvahiSServiceTypeBrowser *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 */
    173 void avahi_s_service_type_browser_free(AvahiSServiceTypeBrowser *b);
    174 
    175 /** Callback prototype for AvahiSServiceBrowser events */
    176 typedef 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. */
    188 AvahiSServiceBrowser *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 */
    199 void avahi_s_service_browser_free(AvahiSServiceBrowser *b);
    200 
    201 /** Callback prototype for AvahiSServiceResolver events */
    202 typedef 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. */
    218 AvahiSServiceResolver *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 */
    231 void avahi_s_service_resolver_free(AvahiSServiceResolver *r);
    232 
    233 AVAHI_C_DECL_END
    234 
    235 #endif
    236