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

   1 #ifndef foocorehfoo
   2 #define foocorehfoo
   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 #include <stdio.h>
  26 #include <glib.h>
  27
  28 /** An mDNS responder object */
  29 typedef struct AvahiServer AvahiServer;
  30
  31 /** A locally registered DNS resource record */
  32 typedef struct AvahiEntry AvahiEntry;
  33
  34 /** A group of locally registered DNS RRs */
  35 typedef struct AvahiEntryGroup AvahiEntryGroup;
  36
  37 #include <avahi-common/address.h>
  38 #include <avahi-common/rr.h>
  39 #include <avahi-common/alternative.h>
  40
  41 /** States of a server object */
  42 typedef enum {
  43     AVAHI_SERVER_INVALID = -1,     /**< Invalid state (initial) */
  44     AVAHI_SERVER_REGISTERING = 0,  /**< Host RRs are being registered */
  45     AVAHI_SERVER_RUNNING,          /**< All host RRs have been established */
  46     AVAHI_SERVER_COLLISION,        /**< There is a collision with a host RR. All host RRs have been withdrawn, the user should set a new host name via avahi_server_set_host_name() */
  47     AVAHI_SERVER_SLEEPING          /**< The host or domain name has changed and the server waits for old entries to be expired */
  48 } AvahiServerState;
  49
  50 /** Flags for server entries */
  51 typedef enum {
  52     AVAHI_ENTRY_NULL = 0,          /**< No special flags */
  53     AVAHI_ENTRY_UNIQUE = 1,        /**< The RRset is intended to be unique */
  54     AVAHI_ENTRY_NOPROBE = 2,       /**< Though the RRset is intended to be unique no probes shall be sent */
  55     AVAHI_ENTRY_NOANNOUNCE = 4,    /**< Do not announce this RR to other hosts */
  56     AVAHI_ENTRY_ALLOWMUTIPLE = 8   /**< Allow multiple local records of this type, even if they are intended to be unique */
  57 } AvahiEntryFlags;
  58
  59 /** States of an entry group object */
  60 typedef enum {
  61     AVAHI_ENTRY_GROUP_UNCOMMITED = -1,   /**< The group has not yet been commited, the user must still call avahi_entry_group_commit() */
  62     AVAHI_ENTRY_GROUP_REGISTERING = 0,   /**< The entries of the group are currently being registered */
  63     AVAHI_ENTRY_GROUP_ESTABLISHED,       /**< The entries have successfully been established */
  64     AVAHI_ENTRY_GROUP_COLLISION          /**< A name collision for one of the entries in the group has been detected, the entries have been withdrawn */
  65 } AvahiEntryGroupState;
  66
  67 /** Prototype for callback functions which are called whenever the state of an AvahiServer object changes */
  68 typedef void (*AvahiServerCallback) (AvahiServer *s, AvahiServerState state, gpointer userdata);
  69
  70 /** Prototype for callback functions which are called whenever the state of an AvahiEntryGroup object changes */
  71 typedef void (*AvahiEntryGroupCallback) (AvahiServer *s, AvahiEntryGroup *g, AvahiEntryGroupState state, gpointer userdata);
  72
  73 /** Stores configuration options for a server instance */
  74 typedef struct AvahiServerConfig {
  75     gchar *host_name;                      /**< Default host name. If left empty defaults to the result of gethostname(2) of the libc */
  76     gchar *domain_name;                    /**< Default domain name. If left empty defaults to .local */
  77     gboolean use_ipv4;                     /**< Enable IPv4 support */
  78     gboolean use_ipv6;                     /**< Enable IPv6 support */
  79     gboolean publish_hinfo;                /**< Register a HINFO record for the host containing the local OS and CPU type */
  80     gboolean publish_addresses;            /**< Register A, AAAA and PTR records for all local IP addresses */
  81     gboolean publish_workstation;          /**< Register a _workstation._tcp service */
  82     gboolean publish_domain;               /**< Announce the local domain for browsing */
  83     gboolean check_response_ttl;           /**< If enabled the server ignores all incoming responses with IP TTL != 255. Newer versions of the RFC do no longer contain this check, so it is disabled by default. */
  84     gboolean use_iff_running;        /**< Require IFF_RUNNING on local network interfaces. This is the official way to check for link beat. Unfortunately this doesn't work with all drivers. So bettere leave this off. */
  85     gboolean enable_reflector;             /**< Reflect incoming mDNS traffic to all local networks. This allows mDNS based network browsing beyond ethernet borders */
  86     gboolean reflect_ipv;                  /**< if enable_reflector is TRUE, enable/disable reflecting between IPv4 and IPv6 */
  87 } AvahiServerConfig;
  88
  89 /** Allocate a new mDNS responder object. */
  90 AvahiServer *avahi_server_new(
  91     GMainContext *c,               /**< The GLIB main loop context to attach to */
  92     const AvahiServerConfig *sc,   /**< If non-NULL a pointer to a configuration structure for the server. The server makes an internal deep copy of this structure, so you may free it using avahi_server_config_done() immediately after calling this function. */
  93     AvahiServerCallback callback,  /**< A callback which is called whenever the state of the server changes */
  94     gpointer userdata              /**< An opaque pointer which is passed to the callback function */);
  95
  96 /** Free an mDNS responder object */
  97 void avahi_server_free(AvahiServer* s);
  98
  99 /** Fill in default values for a server configuration structure. If you
 100  * make use of an AvahiServerConfig structure be sure to initialize
 101  * it with this function for the sake of upwards library
 102  * compatibility. This call may allocate strings on the heap. To
 103  * release this memory make sure to call
 104  * avahi_server_config_done(). If you want to replace any strings in
 105  * the structure be sure to free the strings filled in by this
 106  * function with g_free() first and allocate the replacements with
 107  * g_malloc() (or g_strdup()).*/
 108 AvahiServerConfig* avahi_server_config_init(
 109    AvahiServerConfig *c /**< A structure which shall be filled in */ );
 110
 111 /** Make a deep copy of the configuration structure *c to *ret. */
 112 AvahiServerConfig* avahi_server_config_copy(
 113     AvahiServerConfig *ret /**< destination */,
 114     const AvahiServerConfig *c /**< source */);
 115
 116 /** Free the data in a server configuration structure. */
 117 void avahi_server_config_free(AvahiServerConfig *c);
 118
 119 /** Return the currently chosen domain name of the server object. The
 120  * return value points to an internally allocated string. Be sure to
 121  * make a copy of the string before calling any other library
 122  * functions. */
 123 const gchar* avahi_server_get_domain_name(AvahiServer *s);
 124
 125 /** Return the currently chosen host name. The return value points to a internally allocated string. */
 126 const gchar* avahi_server_get_host_name(AvahiServer *s);
 127
 128 /** Return the currently chosen host name as a FQDN ("fully qualified
 129  * domain name", i.e. the concatenation of the host and domain
 130  * name). The return value points to a internally allocated string. */
 131 const gchar* avahi_server_get_host_name_fqdn(AvahiServer *s);
 132
 133 /** Change the host name of a running mDNS responder. This will drop
 134 all automicatilly generated RRs and readd them with the new
 135 name. Since the responder has to probe for the new RRs this function
 136 takes some time to take effect altough it returns immediately. This
 137 function is intended to be called when a host name conflict is
 138 reported using AvahiServerCallback. The caller should readd all user
 139 defined RRs too since they otherwise continue to point to the outdated
 140 host name..*/
 141 gint avahi_server_set_host_name(AvahiServer *s, const gchar *host_name);
 142
 143 /** Change the domain name of a running mDNS responder. The same rules
 144  * as with avahi_server_set_host_name() apply. */
 145 gint avahi_server_set_domain_name(AvahiServer *s, const gchar *domain_name);
 146
 147 /** Return the opaque user data pointer attached to a server object */
 148 gpointer avahi_server_get_data(AvahiServer *s);
 149
 150 /** Change the opaque user data pointer attached to a server object */
 151 void avahi_server_set_data(AvahiServer *s, gpointer userdata);
 152
 153 /** Return the current state of the server object */
 154 AvahiServerState avahi_server_get_state(AvahiServer *s);
 155
 156 /** Iterate through all local entries of the server. (when g is NULL)
 157  * or of a specified entry group. At the first call state should point
 158  * to a NULL initialized void pointer, That pointer is used to track
 159  * the current iteration. It is not safe to call any other
 160  * avahi_server_xxx() function during the iteration. If the last entry
 161  * has been read, NULL is returned. */
 162 const AvahiRecord *avahi_server_iterate(AvahiServer *s, AvahiEntryGroup *g, void **state);
 163
 164 /** Dump the current server status to the specified FILE object */
 165 void avahi_server_dump(AvahiServer *s, FILE *f);
 166
 167 /** Create a new entry group. The specified callback function is
 168  * called whenever the state of the group changes. Use entry group
 169  * objects to keep track of you RRs. Add new RRs to a group using
 170  * avahi_server_add_xxx(). Make sure to call avahi_entry_group_commit()
 171  * to start the registration process for your RRs */
 172 AvahiEntryGroup *avahi_entry_group_new(AvahiServer *s, AvahiEntryGroupCallback callback, gpointer userdata);
 173
 174 /** Free an entry group. All RRs assigned to the group are removed from the server */
 175 void avahi_entry_group_free(AvahiEntryGroup *g);
 176
 177 /** Commit an entry group. This starts the probing and registration process for all RRs in the group */
 178 gint avahi_entry_group_commit(AvahiEntryGroup *g);
 179
 180 /** Return the current state of the specified entry group */
 181 AvahiEntryGroupState avahi_entry_group_get_state(AvahiEntryGroup *g);
 182
 183 /** Change the opaque user data pointer attached to an entry group object */
 184 void avahi_entry_group_set_data(AvahiEntryGroup *g, gpointer userdata);
 185
 186 /** Return the opaque user data pointer currently set for the entry group object */
 187 gpointer avahi_entry_group_get_data(AvahiEntryGroup *g);
 188
 189 /** Add a new resource record to the server. Returns 0 on success, negative otherwise. */
 190 gint avahi_server_add(
 191     AvahiServer *s,           /**< The server object to add this record to */
 192     AvahiEntryGroup *g,       /**< An entry group object if this new record shall be attached to one, or NULL. If you plan to remove the record sometime later you a required to pass an entry group object here. */
 193     AvahiIfIndex interface,   /**< A numeric index of a network interface to attach this record to, or AVAHI_IF_UNSPEC to attach this record to all interfaces */
 194     AvahiProtocol protocol,   /**< A protocol family to attach this record to. One of the AVAHI_PROTO_xxx constants. Use AVAHI_PROTO_UNSPEC to make this record available on all protocols (wich means on both IPv4 and IPv6). */
 195     AvahiEntryFlags flags,    /**< Special flags for this record */
 196     AvahiRecord *r            /**< The record to add. This function increases the reference counter of this object. */   );
 197
 198 gint avahi_server_add_ptr(
 199     AvahiServer *s,
 200     AvahiEntryGroup *g,
 201     AvahiIfIndex interface,
 202     AvahiProtocol protocol,
 203     AvahiEntryFlags flags,
 204     guint32 ttl,
 205     const gchar *name,
 206     const gchar *dest);
 207
 208 gint avahi_server_add_address(
 209     AvahiServer *s,
 210     AvahiEntryGroup *g,
 211     AvahiIfIndex interface,
 212     AvahiProtocol protocol,
 213     AvahiEntryFlags flags,
 214     const gchar *name,
 215     AvahiAddress *a);
 216
 217 gint avahi_server_add_text(
 218     AvahiServer *s,
 219     AvahiEntryGroup *g,
 220     AvahiIfIndex interface,
 221     AvahiProtocol protocol,
 222     AvahiEntryFlags flags,
 223     guint32 ttl,
 224     const gchar *name,
 225     ... /* text records, terminated by NULL */);
 226
 227 gint avahi_server_add_text_va(
 228     AvahiServer *s,
 229     AvahiEntryGroup *g,
 230     AvahiIfIndex interface,
 231     AvahiProtocol protocol,
 232     AvahiEntryFlags flags,
 233     guint32 ttl,
 234     const gchar *name,
 235     va_list va);
 236
 237 gint avahi_server_add_text_strlst(
 238     AvahiServer *s,
 239     AvahiEntryGroup *g,
 240     AvahiIfIndex interface,
 241     AvahiProtocol protocol,
 242     AvahiEntryFlags flags,
 243     guint32 ttl,
 244     const gchar *name,
 245     AvahiStringList *strlst);
 246
 247 gint avahi_server_add_service(
 248     AvahiServer *s,
 249     AvahiEntryGroup *g,
 250     AvahiIfIndex interface,
 251     AvahiProtocol protocol,
 252     const gchar *type,
 253     const gchar *name,
 254     const gchar *domain,
 255     const gchar *host,
 256     guint16 port,
 257     ...  /**< text records, terminated by NULL */);
 258
 259 gint avahi_server_add_service_va(
 260     AvahiServer *s,
 261     AvahiEntryGroup *g,
 262     AvahiIfIndex interface,
 263     AvahiProtocol protocol,
 264     const gchar *type,
 265     const gchar *name,
 266     const gchar *domain,
 267     const gchar *host,
 268     guint16 port,
 269     va_list va);
 270
 271 gint avahi_server_add_service_strlst(
 272     AvahiServer *s,
 273     AvahiEntryGroup *g,
 274     AvahiIfIndex interface,
 275     AvahiProtocol protocol,
 276     const gchar *type,
 277     const gchar *name,
 278     const gchar *domain,
 279     const gchar *host,
 280     guint16 port,
 281     AvahiStringList *strlst);
 282
 283 /** The type of DNS server */
 284 typedef enum {
 285     AVAHI_DNS_SERVER_RESOLVE,         /**< Unicast DNS servers for normal resolves (_domain._udp)*/
 286     AVAHI_DNS_SERVER_UPDATE           /**< Unicast DNS servers for updates (_dns-update._udp)*/
 287 } AvahiDNSServerType;
 288
 289 /** Publish the specified unicast DNS server address via mDNS. You may
 290  * browse for records create this way wit
 291  * avahi_dns_server_browser_new(). */
 292 gint avahi_server_add_dns_server_address(
 293     AvahiServer *s,
 294     AvahiEntryGroup *g,
 295     AvahiIfIndex interface,
 296     AvahiProtocol protocol,
 297     const gchar *domain,
 298     AvahiDNSServerType type,
 299     const AvahiAddress *address,
 300     guint16 port /** should be 53 */);
 301
 302 /** Similar to avahi_server_add_dns_server_address(), but specify a
 303 host name instead of an address. The specified host name should be
 304 resolvable via mDNS */
 305 gint avahi_server_add_dns_server_name(
 306     AvahiServer *s,
 307     AvahiEntryGroup *g,
 308     AvahiIfIndex interface,
 309     AvahiProtocol protocol,
 310     const gchar *domain,
 311     AvahiDNSServerType type,
 312     const gchar *name,
 313     guint16 port /** should be 53 */);
 314
 315 typedef enum {
 316     AVAHI_BROWSER_NEW = 0,
 317     AVAHI_BROWSER_REMOVE = -1
 318 } AvahiBrowserEvent;
 319
 320 typedef enum {
 321     AVAHI_RESOLVER_FOUND = 0,
 322     AVAHI_RESOLVER_TIMEOUT = -1
 323 } AvahiResolverEvent;
 324
 325
 326 typedef struct AvahiRecordBrowser AvahiRecordBrowser;
 327 typedef void (*AvahiRecordBrowserCallback)(AvahiRecordBrowser *b, AvahiIfIndex interface, AvahiProtocol protocol, AvahiBrowserEvent event, AvahiRecord *record, gpointer userdata);
 328 AvahiRecordBrowser *avahi_record_browser_new(AvahiServer *server, AvahiIfIndex interface, AvahiProtocol protocol, AvahiKey *key, AvahiRecordBrowserCallback callback, gpointer userdata);
 329 void avahi_record_browser_free(AvahiRecordBrowser *b);
 330
 331 typedef struct AvahiHostNameResolver AvahiHostNameResolver;
 332 typedef void (*AvahiHostNameResolverCallback)(AvahiHostNameResolver *r, AvahiIfIndex interface, AvahiProtocol protocol, AvahiResolverEvent event, const gchar *host_name, const AvahiAddress *a, gpointer userdata);
 333 AvahiHostNameResolver *avahi_host_name_resolver_new(AvahiServer *server, AvahiIfIndex interface, AvahiProtocol protocol, const gchar *host_name, AvahiProtocol aprotocol, AvahiHostNameResolverCallback calback, gpointer userdata);
 334 void avahi_host_name_resolver_free(AvahiHostNameResolver *r);
 335
 336 typedef struct AvahiAddressResolver AvahiAddressResolver;
 337 typedef void (*AvahiAddressResolverCallback)(AvahiAddressResolver *r, AvahiIfIndex interface, AvahiProtocol protocol, AvahiResolverEvent event, const AvahiAddress *a, const gchar *host_name, gpointer userdata);
 338 AvahiAddressResolver *avahi_address_resolver_new(AvahiServer *server, AvahiIfIndex interface, AvahiProtocol protocol, const AvahiAddress *address, AvahiAddressResolverCallback calback, gpointer userdata);
 339 void avahi_address_resolver_free(AvahiAddressResolver *r);
 340
 341 /** The type of domain to browse for */
 342 typedef enum {
 343     AVAHI_DOMAIN_BROWSER_REGISTER,          /**< Browse for a list of available registering domains */
 344     AVAHI_DOMAIN_BROWSER_REGISTER_DEFAULT,  /**< Browse for the default registering domain */
 345     AVAHI_DOMAIN_BROWSER_BROWSE,            /**< Browse for a list of available browsing domains */
 346     AVAHI_DOMAIN_BROWSER_BROWSE_DEFAULT,    /**< Browse for the default browsing domain */
 347     AVAHI_DOMAIN_BROWSER_BROWSE_LEGACY      /**< Legacy browse domain - see DNS-SD spec for more information */
 348 } AvahiDomainBrowserType;
 349
 350 typedef struct AvahiDomainBrowser AvahiDomainBrowser;
 351 typedef void (*AvahiDomainBrowserCallback)(AvahiDomainBrowser *b, AvahiIfIndex interface, AvahiProtocol protocol, AvahiBrowserEvent event, const gchar *domain, gpointer userdata);
 352 AvahiDomainBrowser *avahi_domain_browser_new(AvahiServer *server, AvahiIfIndex interface, AvahiProtocol protocol, const gchar *domain, AvahiDomainBrowserType type, AvahiDomainBrowserCallback callback, gpointer userdata);
 353 void avahi_domain_browser_free(AvahiDomainBrowser *b);
 354
 355 typedef struct AvahiServiceTypeBrowser AvahiServiceTypeBrowser;
 356 typedef void (*AvahiServiceTypeBrowserCallback)(AvahiServiceTypeBrowser *b, AvahiIfIndex interface, AvahiProtocol protocol, AvahiBrowserEvent event, const gchar *type, const gchar *domain, gpointer userdata);
 357 AvahiServiceTypeBrowser *avahi_service_type_browser_new(AvahiServer *server, AvahiIfIndex interface, AvahiProtocol protocol, const gchar *domain, AvahiServiceTypeBrowserCallback callback, gpointer userdata);
 358 void avahi_service_type_browser_free(AvahiServiceTypeBrowser *b);
 359
 360 typedef struct AvahiServiceBrowser AvahiServiceBrowser;
 361 typedef void (*AvahiServiceBrowserCallback)(AvahiServiceBrowser *b, AvahiIfIndex interface, AvahiProtocol protocol, AvahiBrowserEvent event, const gchar *name, const gchar *type, const gchar *domain, gpointer userdata);
 362 AvahiServiceBrowser *avahi_service_browser_new(AvahiServer *server, AvahiIfIndex interface, AvahiProtocol protocol, const gchar *service_type, const gchar *domain, AvahiServiceBrowserCallback callback, gpointer userdata);
 363 void avahi_service_browser_free(AvahiServiceBrowser *b);
 364
 365 typedef struct AvahiServiceResolver AvahiServiceResolver;
 366 typedef void (*AvahiServiceResolverCallback)(AvahiServiceResolver *r, AvahiIfIndex interface, AvahiProtocol protocol, AvahiResolverEvent event, const gchar *name, const gchar *type, const gchar *domain, const gchar *host_name, const AvahiAddress *a, guint16 port, AvahiStringList *txt, gpointer userdata);
 367 AvahiServiceResolver *avahi_service_resolver_new(AvahiServer *server, AvahiIfIndex interface, AvahiProtocol protocol, const gchar *name, const gchar *type, const gchar *domain, AvahiProtocol aprotocol, AvahiServiceResolverCallback calback, gpointer userdata);
 368 void avahi_service_resolver_free(AvahiServiceResolver *r);
 369
 370
 371 /** A domain service browser object. Use this to browse for
 372  * conventional unicast DNS servers which may be used to resolve
 373  * conventional domain names */
 374 typedef struct AvahiDNSServerBrowser AvahiDNSServerBrowser;
 375 typedef void (*AvahiDNSServerBrowserCallback)(AvahiDNSServerBrowser *b, AvahiIfIndex interface, AvahiProtocol protocol, AvahiBrowserEvent event, const gchar *host_name, const AvahiAddress *a, guint16 port, gpointer userdata);
 376 AvahiDNSServerBrowser *avahi_dns_server_browser_new(AvahiServer *server, AvahiIfIndex interface, AvahiProtocol protocol, const gchar *domain, AvahiDNSServerType type, AvahiProtocol aprotocol, AvahiDNSServerBrowserCallback callback, gpointer userdata);
 377 void avahi_dns_server_browser_free(AvahiDNSServerBrowser *b);
 378
 379 #endif