git.meshlink.io Git - catta/blob - avahi-common/defs.h

   1 #ifndef foodefshfoo
   2 #define foodefshfoo
   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 defs.h Some common definitions */
  26
  27 #include <avahi-common/cdecl.h>
  28
  29 /** \mainpage
  30  *
  31  * \section choose_api Choosing an API
  32  *
  33  * Avahi provides three programming APIs for integration of
  34  * mDNS/DNS-SD features into your progams:
  35  *
  36  * \li <b>avahi-core</b>: an API for embedding a complete mDNS/DNS-SD stack
  37  * into your software. This is intended for developers of embedded
  38  * ampliances only. We dissuade from using this API in normal desktop
  39  * applications since it is not a good idea to run multiple mDNS
  40  * stacks simultaneously on the same host.
  41  * \li <b>the D-Bus API</b>: an extensive D-Bus interface for browsing and
  42  * registering mDNS/DNS-SD services using avahi-daemon. We recommend
  43  * to use this API for software written in any language but
  44  * C. (i.e. Python)
  45  * \li <b>avahi-client</b>: a simplifying C wrapper around the D-Bus API. We
  46  * recommend to use this API in C or C++ progams. The D-Bus internals
  47  * are hidden completely.
  48  *
  49  * All three APIs are very similar, however avahi-core is the most powerful.
  50  *
  51  * In addition to the three APIs described above Avahi supports two
  52  * compatibility libraries:
  53  *
  54  * \li avahi-compat-libdns_sd: the original Bonjour API as documented
  55  * in the header file "dns_sd.h" by Apple Computer, Inc.
  56  *
  57  * \li avahi-compat-howl: the HOWL API as released with HOWL 0.9.8 by
  58  * Porchdog Software.
  59  *
  60  * Please note that these compatibility layers are incomplete and
  61  * generally a waste of resources. We strongly encourage everyone to
  62  * use our native APIs for newly written programs and to port older
  63  * programs to avahi-client!
  64  *
  65  * \section error_reporting Error Reporting
  66  *
  67  * Some notes on the Avahi error handling:
  68  *
  69  * - Error codes are negative integers and defined as AVAHI_ERR_xx
  70  * - If a function returns some kind of non-negative integer value on
  71  * success, a failure is indicated by returning the error code
  72  * directly.
  73  * - If a function returns a pointer of some kind on success, a
  74  * failure is indicated by returning NULL
  75  * - The last error number may be retrieved by calling
  76  * avahi_client_errno()
  77  * - Just like the libc errno variable the Avahi errno is NOT reset to
  78  * AVAHI_OK if a function call succeeds.
  79  * - You may convert a numeric error code into a human readable string
  80  * using avahi_strerror()
  81  * - The constructor function avahi_client_new() returns the error
  82  * code in a call-by-reference argument
  83  *
  84  * \section event_loop Event Loop Abstraction
  85  *
  86  * Avahi uses a simple event loop abstraction laye. A table AvahiPoll
  87  * which contains function pointers for user defined timeout and I/O
  88  * condition event source implementations needs to be passed to
  89  * avahi_client_new(). An adapter for this abstraction layer is
  90  * available for the GLib main loop in the object AvahiGLibPoll. A
  91  * simple stand-alone implementation is available under the name
  92  * AvahiSimplePoll. An adpater for the Qt main loop is available from
  93  * avahi_qt_poll_get().
  94  *
  95  * \section good_publish How to Register Services
  96  *
  97  * - Subscribe to server state changes. Pass a callback function
  98  * pointer to avahi_client_new(). It will be called
  99  * whenever the server state changes.
 100  * - Only register your services when the server is in state
 101  * AVAHI_SERVER_RUNNING. If you register your services in other server
 102  * states they might not be accessible since the local host name is
 103  * not established.
 104  * - Remove your services when the server enters
 105  * AVAHI_SERVER_COLLISION state. Your services may no be reachable
 106  * anymore since the local host name is no longer established.
 107  * - When registering services, use the following algorithm:
 108  *   - Create a new entry group (i.e. avahi_entry_group_new())
 109  *   - Add your service(s)/additional host names (i.e. avahi_entry_group_add_service())
 110  *   - Commit the entry group (i.e. avahi_entry_group_commit())
 111  * - Subscribe to entry group state changes.
 112  * - If the entry group enters AVAHI_ENTRY_GROUP_COLLISION state the
 113  * services of the entry group are automatically removed from the
 114  * server. You may immediately add your services back to the entry
 115  * group (but with new names, perhaps using
 116  * avahi_alternative_service_name()) and commit again. Please do not
 117  * free the entry group and create a new one. This would inhibit some
 118  * traffic limiting algorithms in mDNS.
 119  * - When you need to modify your services (i.e. change the TXT data
 120  * or the port number), use the AVAHI_PUBLISH_UPDATE flag. Please do
 121  * not free the entry group and create a new one. This would inhibit
 122  * some traffic limiting algorithms in mDNS. When changing just the
 123  * TXT data avahi_entry_group_update_txt() is a shortcut for
 124  * AVAHI_PUBLISH_UPDATE. Please note that you cannot use
 125  * AVAHI_PUBLISH_UPDATE when changing the service name! Renaming a
 126  * DNS-SD service is identical to deleting and creating a new one, and
 127  * that's exactly what you should do in that case. First call
 128  * avahi_entry_group_reset() to remove it and than readd it normally.
 129  *
 130  * \section good_browse How to Browse for Services
 131  *
 132  * - For normal applications you need to call avahi_service_browser_new()
 133  * for the service type you want to browse for. Use
 134  * avahi_client_resolve_service() to acquire service data for a a service
 135  * name.
 136  * - You can use avahi_domain_browser_new() to get a list of announced
 137  * browsing domains. Please note that not all domains whith services
 138  * on the LAN are mandatorily announced.
 139  * - Network monitor software may use avahi_service_type_browser_new()
 140  * to browse for the list of available service types on the LAN. This
 141  * API should NOT be used in normal software since it increases
 142  * traffic immensly. In addition not all DNS-SD implementations
 143  * announce their services in away that they can be found with
 144  * avahi_server_type_browser_new().
 145  * - There is no need to subscribe to server state changes.
 146  *
 147  * \section daemon_dies How to Write a Client That Can Deal with Daemon Restarts
 148  *
 149  * With Avahi it is possible to write client applications that can
 150  * deal with Avahi daemon restarts. To accomplish that make sure to
 151  * pass AVAHI_CLIENT_NO_FAIL to avahi_client_new()'s flags
 152  * parameter. That way avahi_client_new() will succeed even when the
 153  * daemon is not running. In that case the object will enter
 154  * AVAHI_CLIENT_CONNECTING state. As soon as the daemon becomes
 155  * available the object will enter one of the AVAHI_CLIENT_S_xxx
 156  * states. Make sure to not create browsers or entry groups before the
 157  * client object has entered one of those states. As usual you will be
 158  * informed about state changes with the callback function supplied to
 159  * avahi_client_new(). If the client is forced to disconnect from the
 160  * server it will enter AVAHI_CLIENT_FAILURE state with
 161  * avahi_client_errno() == AVAHI_ERR_DISCONNECTED. Free the
 162  * AvahiClient object in that case and reconnect to the server anew -
 163  * again with passing AVAHI_CLIENT_NO_FAIL to avahi_client_new().
 164  *
 165  * We encourage to implement this in all software where service
 166  * discovery is not an integral part of application. e.g. use it in
 167  * all kinds of background daemons, but not in software like iChat
 168  * compatible IM software.
 169  *
 170  * For now AVAHI_CLIENT_NO_FAIL cannot deal with D-Bus daemon restarts.
 171  *
 172  * \section domains How to Deal Properly with Browsing Domains
 173  *
 174  * Due to the introduction of wide-area DNS-SD the correct handling of
 175  * domains becomes more important for Avahi enabled applications. All
 176  * applications that offer the user a list of services discovered with
 177  * Avahi should offer some kind of editable drop down box where the
 178  * user can either enter his own domain or select one of those offered
 179  * by AvahiDomainBrowser. The default domain to browse should be the
 180  * one returned by avahi_client_get_domain_name(). The list of domains
 181  * returned by AvahiDomainBrowser is assembled by the browsing domains
 182  * configured in the daemon's configuration file, the domains
 183  * announced inside the default domain, the domains set with the
 184  * environment variable $AVAHI_BROWSE_DOMAINS (colon-seperated) on the
 185  * client side and the domains set in the XDG configuration file
 186  * ~/.config/avahi/browse-domains on the client side (seperated by
 187  * newlines). File managers offering some kind of "Network
 188  * Neighborhood" folder should show the entries of the default domain
 189  * right inside that and offer subfolders for the browsing domains
 190  * returned by AvahiDomainBrowser.
 191  */
 192
 193 AVAHI_C_DECL_BEGIN
 194
 195 /** States of an entry group object */
 196 typedef enum {
 197     AVAHI_ENTRY_GROUP_UNCOMMITED,    /**< The group has not yet been commited, the user must still call avahi_entry_group_commit() */
 198     AVAHI_ENTRY_GROUP_REGISTERING,   /**< The entries of the group are currently being registered */
 199     AVAHI_ENTRY_GROUP_ESTABLISHED,   /**< The entries have successfully been established */
 200     AVAHI_ENTRY_GROUP_COLLISION,     /**< A name collision for one of the entries in the group has been detected, the entries have been withdrawn */
 201     AVAHI_ENTRY_GROUP_FAILURE        /**< Some kind of failure happened, the entries have been withdrawn */
 202 } AvahiEntryGroupState;
 203
 204 /** The type of domain to browse for */
 205 typedef enum {
 206     AVAHI_DOMAIN_BROWSER_BROWSE,            /**< Browse for a list of available browsing domains */
 207     AVAHI_DOMAIN_BROWSER_BROWSE_DEFAULT,    /**< Browse for the default browsing domain */
 208     AVAHI_DOMAIN_BROWSER_REGISTER,          /**< Browse for a list of available registering domains */
 209     AVAHI_DOMAIN_BROWSER_REGISTER_DEFAULT,  /**< Browse for the default registering domain */
 210     AVAHI_DOMAIN_BROWSER_BROWSE_LEGACY,     /**< Legacy browse domain - see DNS-SD spec for more information */
 211     AVAHI_DOMAIN_BROWSER_MAX
 212 } AvahiDomainBrowserType;
 213
 214 /** Some flags for publishing functions */
 215 typedef enum {
 216     AVAHI_PUBLISH_UNIQUE = 1,           /**< For raw records: The RRset is intended to be unique */
 217     AVAHI_PUBLISH_NO_PROBE = 2,         /**< For raw records: Though the RRset is intended to be unique no probes shall be sent */
 218     AVAHI_PUBLISH_NO_ANNOUNCE = 4,      /**< For raw records: Do not announce this RR to other hosts */
 219     AVAHI_PUBLISH_ALLOW_MULTIPLE = 8,   /**< For raw records: Allow multiple local records of this type, even if they are intended to be unique */
 220     AVAHI_PUBLISH_NO_REVERSE = 16,      /**< For address records: don't create a reverse (PTR) entry */
 221     AVAHI_PUBLISH_NO_COOKIE = 32,       /**< For service records: do not implicitly add the local service cookie to TXT data */
 222     AVAHI_PUBLISH_UPDATE = 64,          /**< Update existing records instead of adding new ones */
 223     AVAHI_PUBLISH_USE_WIDE_AREA = 128,  /**< Register the record using wide area DNS (i.e. unicast DNS update) */
 224     AVAHI_PUBLISH_USE_MULTICAST = 256   /**< Register the record using multicast DNS */
 225 } AvahiPublishFlags;
 226
 227 /** Some flags for lookup functions */
 228 typedef enum {
 229     AVAHI_LOOKUP_USE_WIDE_AREA = 1,    /**< Force lookup via wide area DNS */
 230     AVAHI_LOOKUP_USE_MULTICAST = 2,    /**< Force lookup via multicast DNS */
 231     AVAHI_LOOKUP_NO_TXT = 4,           /**< When doing service resolving, don't lookup TXT record */
 232     AVAHI_LOOKUP_NO_ADDRESS = 8        /**< When doing service resolving, don't lookup A/AAAA record */
 233 } AvahiLookupFlags;
 234
 235 /** Some flags for lookup callback functions */
 236 typedef enum {
 237     AVAHI_LOOKUP_RESULT_CACHED = 1,         /**< This response originates from the cache */
 238     AVAHI_LOOKUP_RESULT_WIDE_AREA = 2,      /**< This response originates from wide area DNS */
 239     AVAHI_LOOKUP_RESULT_MULTICAST = 4,      /**< This response originates from multicast DNS */
 240     AVAHI_LOOKUP_RESULT_LOCAL = 8,          /**< This record/service resides on and was announced by the local host. Only available in service and record browsers and only on AVAHI_BROWSER_NEW. */
 241     AVAHI_LOOKUP_RESULT_OUR_OWN = 16,       /**< This service belongs to the same local client as the browser object. Only available in avahi-client, and only for service browsers and only on AVAHI_BROWSER_NEW. */
 242     AVAHI_LOOKUP_RESULT_STATIC = 32         /**< The returned data has been defined statically by some configuration option */
 243 } AvahiLookupResultFlags;
 244
 245 /** Type of callback event when browsing */
 246 typedef enum {
 247     AVAHI_BROWSER_NEW,               /**< The object is new on the network */
 248     AVAHI_BROWSER_REMOVE,            /**< The object has been removed from the network */
 249     AVAHI_BROWSER_CACHE_EXHAUSTED,   /**< One-time event, to notify the user that all entries from the caches have been send */
 250     AVAHI_BROWSER_ALL_FOR_NOW,       /**< One-time event, to notify the user that more records will probably not show up in the near future, i.e. all cache entries have been read and all static servers been queried */
 251     AVAHI_BROWSER_FAILURE            /**< Browsing failed due to some reason which can be retrieved using avahi_server_errno()/avahi_client_errno() */
 252 } AvahiBrowserEvent;
 253
 254 /** Type of callback event when resolving */
 255 typedef enum {
 256     AVAHI_RESOLVER_FOUND,          /**< RR found, resolving successful */
 257     AVAHI_RESOLVER_FAILURE         /**< Resolving failed due to some reason which can be retrieved using avahi_server_errno()/avahi_client_errno() */
 258 } AvahiResolverEvent;
 259
 260 /** States of a server object */
 261 typedef enum {
 262     AVAHI_SERVER_INVALID,          /**< Invalid state (initial) */
 263     AVAHI_SERVER_REGISTERING,      /**< Host RRs are being registered */
 264     AVAHI_SERVER_RUNNING,          /**< All host RRs have been established */
 265     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() */
 266     AVAHI_SERVER_FAILURE           /**< Some fatal failure happened, the server is unable to proceed */
 267 } AvahiServerState;
 268
 269 /** For every service a special TXT item is implicitly added, which
 270  * contains a random cookie which is private to the local daemon. This
 271  * can be used by clients to determine if two services on two
 272  * different subnets are effectively the same. */
 273 #define AVAHI_SERVICE_COOKIE "org.freedesktop.Avahi.cookie"
 274
 275 /** In invalid cookie as special value */
 276 #define AVAHI_SERVICE_COOKIE_INVALID (0)
 277
 278 /** DNS record types, see RFC 1035 */
 279 enum {
 280     AVAHI_DNS_TYPE_A = 0x01,
 281     AVAHI_DNS_TYPE_NS = 0x02,
 282     AVAHI_DNS_TYPE_CNAME = 0x05,
 283     AVAHI_DNS_TYPE_SOA = 0x06,
 284     AVAHI_DNS_TYPE_PTR = 0x0C,
 285     AVAHI_DNS_TYPE_HINFO = 0x0D,
 286     AVAHI_DNS_TYPE_MX = 0x0F,
 287     AVAHI_DNS_TYPE_TXT = 0x10,
 288     AVAHI_DNS_TYPE_AAAA = 0x1C,
 289     AVAHI_DNS_TYPE_SRV = 0x21,
 290 };
 291
 292 /** DNS record classes, see RFC 1035 */
 293 enum {
 294     AVAHI_DNS_CLASS_IN = 0x01,          /**< Probably the only class we will ever use */
 295 };
 296
 297 /** The default TTL for RRs which contain a host name of some kind. */
 298 #define AVAHI_DEFAULT_TTL_HOST_NAME (120)
 299
 300 /** The default TTL for all other records. */
 301 #define AVAHI_DEFAULT_TTL (75*60)
 302
 303 AVAHI_C_DECL_END
 304
 305 #endif