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