git.meshlink.io Git - catta/blob - include/catta/lookup.h

   1 #ifndef foolookuphfoo
   2 #define foolookuphfoo
   3
   4 /***
   5   This file is part of catta.
   6
   7   catta 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   catta 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 catta; 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 catta/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 CattaSRecordBrowser CattaSRecordBrowser;
  30
  31 /** A host name to IP adddress resolver object */
  32 typedef struct CattaSHostNameResolver CattaSHostNameResolver;
  33
  34 /** An IP address to host name resolver object ("reverse lookup") */
  35 typedef struct CattaSAddressResolver CattaSAddressResolver;
  36
  37 /** A local domain browsing object. May be used to enumerate domains used on the local LAN */
  38 typedef struct CattaSDomainBrowser CattaSDomainBrowser;
  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 CattaSServiceTypeBrowser CattaSServiceTypeBrowser;
  42
  43 /** A DNS-SD service browser. Use this to enumerate available services of a certain kind on the local LAN. Use CattaSServiceResolver to get specific service data like address and port for a service. */
  44 typedef struct CattaSServiceBrowser CattaSServiceBrowser;
  45
  46 /** A DNS-SD service resolver.  Use this to retrieve addres, port and TXT data for a DNS-SD service */
  47 typedef struct CattaSServiceResolver CattaSServiceResolver;
  48
  49 #include <catta/cdecl.h>
  50 #include <catta/defs.h>
  51 #include <catta/core.h>
  52
  53 CATTA_C_DECL_BEGIN
  54
  55 /** Callback prototype for CattaSRecordBrowser events */
  56 typedef void (*CattaSRecordBrowserCallback)(
  57     CattaSRecordBrowser *b,          /**< The CattaSRecordBrowser object that is emitting this callback */
  58     CattaIfIndex iface,          /**< Logical OS network interface number the record was found on */
  59     CattaProtocol protocol,          /**< Protocol number the record was found. */
  60     CattaBrowserEvent event,         /**< Browsing event, either CATTA_BROWSER_NEW or CATTA_BROWSER_REMOVE */
  61     CattaRecord *record,             /**< The record that was found */
  62     CattaLookupResultFlags flags,  /**< Lookup flags */
  63     void* userdata                   /**< Arbitrary user data passed to catta_s_record_browser_new() */ );
  64
  65 /** Create a new browsing object for arbitrary RRs */
  66 CattaSRecordBrowser *catta_s_record_browser_new(
  67     CattaServer *server,                    /**< The server object to which attach this query */
  68     CattaIfIndex iface,                 /**< Logical OS interface number where to look for the records, or CATTA_IF_UNSPEC to look on interfaces */
  69     CattaProtocol protocol,                 /**< Protocol number to use when looking for the record, or CATTA_PROTO_UNSPEC to look on all protocols */
  70     CattaKey *key,                          /**< The search key */
  71     CattaLookupFlags flags,                 /**< Lookup flags. Must have set either CATTA_LOOKUP_FORCE_WIDE_AREA or CATTA_LOOKUP_FORCE_MULTICAST, since domain based detection is not available here. */
  72     CattaSRecordBrowserCallback 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 CattaSRecordBrowser object */
  76 void catta_s_record_browser_free(CattaSRecordBrowser *b);
  77
  78 /** Callback prototype for CattaSHostNameResolver events */
  79 typedef void (*CattaSHostNameResolverCallback)(
  80     CattaSHostNameResolver *r,
  81     CattaIfIndex iface,
  82     CattaProtocol protocol,
  83     CattaResolverEvent event, /**< Resolving event */
  84     const char *host_name,   /**< Host name which should be resolved. May differ in case from the query */
  85     const CattaAddress *a,    /**< The address, or NULL if the host name couldn't be resolved. */
  86     CattaLookupResultFlags flags,  /**< Lookup flags */
  87     void* userdata);
  88
  89 /** Create an CattaSHostNameResolver object for resolving a host name to an adddress. See CattaSRecordBrowser for more info on the paramters. */
  90 CattaSHostNameResolver *catta_s_host_name_resolver_new(
  91     CattaServer *server,
  92     CattaIfIndex iface,
  93     CattaProtocol protocol,
  94     const char *host_name,                  /**< The host name to look for */
  95     CattaProtocol aprotocol,                /**< The address family of the desired address or CATTA_PROTO_UNSPEC if doesn't matter. */
  96     CattaLookupFlags flags,                 /**< Lookup flags. */
  97     CattaSHostNameResolverCallback calback,
  98     void* userdata);
  99
 100 /** Free a CattaSHostNameResolver object */
 101 void catta_s_host_name_resolver_free(CattaSHostNameResolver *r);
 102
 103 /** Callback prototype for CattaSAddressResolver events */
 104 typedef void (*CattaSAddressResolverCallback)(
 105     CattaSAddressResolver *r,
 106     CattaIfIndex iface,
 107     CattaProtocol protocol,
 108     CattaResolverEvent event,
 109     const CattaAddress *a,
 110     const char *host_name,   /**< A host name for the specified address, if one was found, i.e. event == CATTA_RESOLVER_FOUND */
 111     CattaLookupResultFlags flags,  /**< Lookup flags */
 112     void* userdata);
 113
 114 /** Create an CattaSAddressResolver object. See CattaSRecordBrowser for more info on the paramters. */
 115 CattaSAddressResolver *catta_s_address_resolver_new(
 116     CattaServer *server,
 117     CattaIfIndex iface,
 118     CattaProtocol protocol,
 119     const CattaAddress *address,
 120     CattaLookupFlags flags,                 /**< Lookup flags. */
 121     CattaSAddressResolverCallback calback,
 122     void* userdata);
 123
 124 /** Free an CattaSAddressResolver object */
 125 void catta_s_address_resolver_free(CattaSAddressResolver *r);
 126
 127 /** Callback prototype for CattaSDomainBrowser events */
 128 typedef void (*CattaSDomainBrowserCallback)(
 129     CattaSDomainBrowser *b,
 130     CattaIfIndex iface,
 131     CattaProtocol protocol,
 132     CattaBrowserEvent event,
 133     const char *domain,
 134     CattaLookupResultFlags flags,  /**< Lookup flags */
 135     void* userdata);
 136
 137 /** Create a new CattaSDomainBrowser object */
 138 CattaSDomainBrowser *catta_s_domain_browser_new(
 139     CattaServer *server,
 140     CattaIfIndex iface,
 141     CattaProtocol protocol,
 142     const char *domain,
 143     CattaDomainBrowserType type,
 144     CattaLookupFlags flags,                 /**< Lookup flags. */
 145     CattaSDomainBrowserCallback callback,
 146     void* userdata);
 147
 148 /** Free an CattaSDomainBrowser object */
 149 void catta_s_domain_browser_free(CattaSDomainBrowser *b);
 150
 151 /** Callback prototype for CattaSServiceTypeBrowser events */
 152 typedef void (*CattaSServiceTypeBrowserCallback)(
 153     CattaSServiceTypeBrowser *b,
 154     CattaIfIndex iface,
 155     CattaProtocol protocol,
 156     CattaBrowserEvent event,
 157     const char *type,
 158     const char *domain,
 159     CattaLookupResultFlags flags,  /**< Lookup flags */
 160     void* userdata);
 161
 162 /** Create a new CattaSServiceTypeBrowser object. */
 163 CattaSServiceTypeBrowser *catta_s_service_type_browser_new(
 164     CattaServer *server,
 165     CattaIfIndex iface,
 166     CattaProtocol protocol,
 167     const char *domain,
 168     CattaLookupFlags flags,                 /**< Lookup flags. */
 169     CattaSServiceTypeBrowserCallback callback,
 170     void* userdata);
 171
 172 /** Free an CattaSServiceTypeBrowser object */
 173 void catta_s_service_type_browser_free(CattaSServiceTypeBrowser *b);
 174
 175 /** Callback prototype for CattaSServiceBrowser events */
 176 typedef void (*CattaSServiceBrowserCallback)(
 177     CattaSServiceBrowser *b,
 178     CattaIfIndex iface,
 179     CattaProtocol protocol,
 180     CattaBrowserEvent 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     CattaLookupResultFlags flags,  /**< Lookup flags */
 185     void* userdata);
 186
 187 /** Create a new CattaSServiceBrowser object. */
 188 CattaSServiceBrowser *catta_s_service_browser_new(
 189     CattaServer *server,
 190     CattaIfIndex iface,
 191     CattaProtocol protocol,
 192     const char *service_type /** DNS-SD service type, e.g. "_http._tcp" */,
 193     const char *domain,
 194     CattaLookupFlags flags,                 /**< Lookup flags. */
 195     CattaSServiceBrowserCallback callback,
 196     void* userdata);
 197
 198 /** Free an CattaSServiceBrowser object */
 199 void catta_s_service_browser_free(CattaSServiceBrowser *b);
 200
 201 /** Callback prototype for CattaSServiceResolver events */
 202 typedef void (*CattaSServiceResolverCallback)(
 203     CattaSServiceResolver *r,
 204     CattaIfIndex iface,
 205     CattaProtocol protocol,
 206     CattaResolverEvent event,  /**< Is CATTA_RESOLVER_FOUND when the service was resolved successfully, and everytime it changes. Is CATTA_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 CattaAddress *a,   /**< The resolved host name */
 212     uint16_t port,            /**< Service name */
 213     CattaStringList *txt,    /**< TXT record data */
 214     CattaLookupResultFlags flags,  /**< Lookup flags */
 215     void* userdata);
 216
 217 /** Create a new CattaSServiceResolver object. The specified callback function will be called with the resolved service data. */
 218 CattaSServiceResolver *catta_s_service_resolver_new(
 219     CattaServer *server,
 220     CattaIfIndex iface,
 221     CattaProtocol protocol,
 222     const char *name,
 223     const char *type,
 224     const char *domain,
 225     CattaProtocol aprotocol,    /**< Address family of the desired service address. Use CATTA_PROTO_UNSPEC if you don't care */
 226     CattaLookupFlags flags,                 /**< Lookup flags. */
 227     CattaSServiceResolverCallback calback,
 228     void* userdata);
 229
 230 /** Free an CattaSServiceResolver object */
 231 void catta_s_service_resolver_free(CattaSServiceResolver *r);
 232
 233 CATTA_C_DECL_END
 234
 235 #endif